@capra/core 1.5.3 → 1.6.0

package/docs/core-visuallyhidden--design.md

@@ -0,0 +1,87 @@
+# Core/VisuallyHidden - Design
+
+VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
+
+## Overview
+
+VisuallyHidden is a utility component that removes content from the visual flow while keeping it accessible to assistive technologies such as screen readers. It uses a well-established CSS technique that clips the element to a 1×1 pixel area without using `display: none` or `visibility: hidden`, which would remove it from the accessibility tree entirely.
+
+Use VisuallyHidden when you need to provide context or labels for screen reader users that would be redundant or unnecessary in the visual design.
+
+## Use Cases
+
+### Hidden labels for icon-only controls
+
+Icon-only buttons and controls must have accessible names. Wrap a text label in VisuallyHidden to provide one without affecting the visual design.
+
+### Supplementary link text
+
+Links like "Read more" lack context when read in isolation. Use VisuallyHidden to append descriptive text that screen readers announce.
+
+### Form labels
+
+When a form input has a visible placeholder but no visible label, use VisuallyHidden to associate a proper `<label>` element with the input.
+
+### Skip links
+
+Skip navigation links allow keyboard users to bypass repeated content. The link text can be visually hidden until it receives focus.
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do use VisuallyHidden to provide accessible names for icon-only buttons and controls.
+</p>
+
+**Don't**
+
+<p>
+  Don't use VisuallyHidden to hide content that all users should see. If the content is meaningful, it should be visible.
+</p>
+
+**Do**
+
+<p>
+  Do use VisuallyHidden to add context to ambiguous links like "Read more" or "Learn more".
+</p>
+
+**Don't**
+
+<p>
+  Don't use 
+
+  `display: none`
+
+   or 
+
+  `visibility: hidden`
+
+   when content should remain available to assistive technologies.
+</p>
+
+## Accessibility
+
+### Purpose
+
+VisuallyHidden exists specifically to improve accessibility. It bridges the gap between visual design and the information needs of assistive technology users.
+
+### When to Use
+
+### WCAG 1.1.1 — Non-text Content (Level A)
+
+Provide text alternatives for non-text content such as icon-only buttons. VisuallyHidden allows you to add an accessible name without altering the visual design.
+
+### WCAG 2.4.4 — Link Purpose (Level A)
+
+Links should make sense out of context. When visual context makes the purpose clear but the link text alone is ambiguous (e.g., "Read more"), use VisuallyHidden to add clarifying text.
+
+### WCAG 2.4.6 — Headings and Labels (Level AA)
+
+Form inputs should have descriptive labels. When a visible label would be redundant with other visual cues, VisuallyHidden can provide a programmatic label for assistive technologies.
+
+### Important Notes
+
+* VisuallyHidden content **is not** hidden from screen readers — that is its entire purpose.
+* Do **not** use `aria-hidden="true"` on VisuallyHidden or its children, as this would negate its purpose.
+* Prefer `aria-label` or `aria-labelledby` when labeling a single element. Use VisuallyHidden when you need to provide more complex or multi-element content to assistive technologies.

package/docs/core-visuallyhidden--usage.md

@@ -0,0 +1,35 @@
+# Core/VisuallyHidden - Usage
+
+VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | Yes | `--` | `--` |
+
+## Usage
+
+```tsx
+import { VisuallyHidden } from '@cribl/capra-core';
+
+// Accessible label for an icon-only button
+<button>
+  🔔 <VisuallyHidden>Notifications</VisuallyHidden>
+</button>
+
+// Descriptive link text
+<a href="/docs">
+  Read more<VisuallyHidden> about our API documentation</VisuallyHidden>
+</a>
+
+// Hidden form label
+<VisuallyHidden>
+  <label htmlFor="search">Search</label>
+</VisuallyHidden>
+<input id="search" type="search" placeholder="Search..." />
+```
+
+## How It Works
+
+The component renders a `<span>` element with CSS that clips it to a 1×1 pixel area using `clip-path: inset(100%)`. This keeps the content in the DOM and accessibility tree while removing it from the visual layout.
+
+The `:not(:focus):not(:active)` selector ensures that if a focusable element (like a skip link) is nested inside, it becomes visible when focused.

package/docs/history-changelogs-capra-core--docs.md

@@ -0,0 +1,49 @@
+# History/Changelogs/@capra-core
+
+### 1.6.0
+
+#### Minor Changes
+
+* [e99f46d](https://bitbucket.org/cribl/capra-ui/commits/e99f46d): Include LLM-friendly docs in published packages
+
+#### Patch Changes
+
+* [ce30088](https://bitbucket.org/cribl/capra-ui/commits/ce30088): Increase `Modal` z-index so it layers correctly
+* [8a1bbe5](https://bitbucket.org/cribl/capra-ui/commits/8a1bbe5): Update `TextInput` internal spacing so Chrome's autofill backgrounds look better
+* Updated dependencies [e99f46d](https://bitbucket.org/cribl/capra-ui/commits/e99f46d) — Include LLM-friendly docs in published packages
+  * @capra/icons\@1.7.0
+
+### 1.5.3
+
+#### Patch Changes
+
+* [5387e9d](https://bitbucket.org/cribl/capra-ui/commits/5387e9d): Fix an issue where `EmptyState` crashed in Webpack bundles
+
+### 1.5.2
+
+#### Patch Changes
+
+* [961667d](https://bitbucket.org/cribl/capra-ui/commits/961667d): Update the `icon` prop for `Tag` to accept logos from `@capra/icons/logos`.
+* [1128996](https://bitbucket.org/cribl/capra-ui/commits/1128996): Add documentation links to README and `package.json`
+* Updated dependencies [1128996](https://bitbucket.org/cribl/capra-ui/commits/1128996) — Add documentation links to README and `package.json`
+  * @capra/icons\@1.6.1
+
+### 1.5.1
+
+#### Patch Changes
+
+* [7fdf2f5](https://bitbucket.org/cribl/capra-ui/commits/7fdf2f5): Fix `TabNav` horizontal submenu visibility so click, hover, keyboard toggles, `Escape`, and focus containment behave consistently. Remove margin.
+* [363909c](https://bitbucket.org/cribl/capra-ui/commits/363909c): Import `EmptyState` illustrations directly to help with tree-shaking and load times
+* [0219174](https://bitbucket.org/cribl/capra-ui/commits/0219174): Drawer no longer closes on browser Back, and left-placed drawers now use the same close easing behavior as right-placed drawers.
+* [186bcfe](https://bitbucket.org/cribl/capra-ui/commits/186bcfe): Reduce `Tooltip` hover delay to 500ms
+
+### 1.5.0
+
+#### Minor Changes
+
+* [30b2a43](https://bitbucket.org/cribl/capra-ui/commits/30b2a43): Prepare packages for publishing to NPM
+
+#### Patch Changes
+
+* Updated dependencies [30b2a43](https://bitbucket.org/cribl/capra-ui/commits/30b2a43) — Prepare packages for publishing to NPM
+  * @capra/icons\@1.6.0

package/docs/index.md

@@ -0,0 +1,110 @@
+# @capra/core
+
+This file contains links to the documentation for the `@capra/core` package. This is a local mirror of the documentation located at https://capra.cribl.io/llms.txt.
+
+Embedded documentation is available on the filesystem for each of these packages:
+
+- `@capra/core`
+- `@capra/domain`
+- `@capra/icons`
+- `@capra/theme`
+
+## Documentation
+
+- [Conventions](./conventions--docs.md)
+- [Using Capra](./using-capra--docs.md)
+- [Core/Alert - Design](./core-alert--design.md)
+- [Core/Alert - Usage](./core-alert--usage.md)
+- [Core/Anchor - Design](./core-anchor--design.md)
+- [Core/Anchor - Usage](./core-anchor--usage.md)
+- [Core/AutocompleteField - Design](./core-autocompletefield--design.md)
+- [Core/AutocompleteField - Usage](./core-autocompletefield--usage.md)
+- [Core/Badge - Design](./core-badge--design.md)
+- [Core/Badge - Usage](./core-badge--usage.md)
+- [Core/Breadcrumbs - Design](./core-breadcrumbs--design.md)
+- [Core/Breadcrumbs - Usage](./core-breadcrumbs--usage.md)
+- [Core/Button - Design](./core-button--design.md)
+- [Core/Button - Usage](./core-button--usage.md)
+- [Core/ButtonLink - Design](./core-buttonlink--design.md)
+- [Core/ButtonLink - Usage](./core-buttonlink--usage.md)
+- [Core/Card - Design](./core-card--design.md)
+- [Core/Card - Usage](./core-card--usage.md)
+- [Core/Checkbox - Design](./core-checkbox--design.md)
+- [Core/Checkbox - Usage](./core-checkbox--usage.md)
+- [Core/Collapse - Design](./core-collapse--design.md)
+- [Core/Collapse - Usage](./core-collapse--usage.md)
+- [Core/DatePickerField - Design](./core-datepickerfield--design.md)
+- [Core/DatePickerField - Usage](./core-datepickerfield--usage.md)
+- [Core/DateRangePickerField - Design](./core-daterangepickerfield--design.md)
+- [Core/DateRangePickerField - Usage](./core-daterangepickerfield--usage.md)
+- [Core/Divider - Design](./core-divider--design.md)
+- [Core/Divider - Usage](./core-divider--usage.md)
+- [Core/Drawer - Design](./core-drawer--design.md)
+- [Core/Drawer - Usage](./core-drawer--usage.md)
+- [Core/EmptyState - Design](./core-emptystate--design.md)
+- [Core/EmptyState - Usage](./core-emptystate--usage.md)
+- [Core/HelperText - Design](./core-helpertext--design.md)
+- [Core/HelperText - Usage](./core-helpertext--usage.md)
+- [Core/IconButton - Design](./core-iconbutton--design.md)
+- [Core/IconButton - Usage](./core-iconbutton--usage.md)
+- [Core/InputRow - Design](./core-inputrow--design.md)
+- [Core/InputRow - Usage](./core-inputrow--usage.md)
+- [Core/Label - Design](./core-label--design.md)
+- [Core/Label - Usage](./core-label--usage.md)
+- [Core/Link - Design](./core-link--design.md)
+- [Core/Link - Usage](./core-link--usage.md)
+- [Core/ListItem - Design](./core-listitem--design.md)
+- [Core/ListItem - Usage](./core-listitem--usage.md)
+- [Core/Menu - Design](./core-menu--design.md)
+- [Core/Menu - Usage](./core-menu--usage.md)
+- [Core/Modal - Design](./core-modal--design.md)
+- [Core/Modal - Usage](./core-modal--usage.md)
+- [Core/NumberField - Design](./core-numberfield--design.md)
+- [Core/NumberField - Usage](./core-numberfield--usage.md)
+- [Core/Pagination - Design](./core-pagination--design.md)
+- [Core/Pagination - Usage](./core-pagination--usage.md)
+- [Core/PasswordField - Design](./core-passwordfield--design.md)
+- [Core/PasswordField - Usage](./core-passwordfield--usage.md)
+- [Core/Pill - Design](./core-pill--design.md)
+- [Core/Pill - Usage](./core-pill--usage.md)
+- [Core/Popover - Design](./core-popover--design.md)
+- [Core/Popover - Usage](./core-popover--usage.md)
+- [Core/Radio - Design](./core-radio--design.md)
+- [Core/Radio - Usage](./core-radio--usage.md)
+- [Core/RadioGroup - Design](./core-radiogroup--design.md)
+- [Core/RadioGroup - Usage](./core-radiogroup--usage.md)
+- [Core/RadioTile - Design](./core-radiotile--design.md)
+- [Core/RadioTile - Usage](./core-radiotile--usage.md)
+- [Core/Ribbon - Design](./core-ribbon--design.md)
+- [Core/Ribbon - Usage](./core-ribbon--usage.md)
+- [Core/Skeleton - Design](./core-skeleton--design.md)
+- [Core/Skeleton - Usage](./core-skeleton--usage.md)
+- [Core/SkeletonGroup - Design](./core-skeletongroup--design.md)
+- [Core/SkeletonGroup - Usage](./core-skeletongroup--usage.md)
+- [Core/Spinner - Design](./core-spinner--design.md)
+- [Core/Spinner - Usage](./core-spinner--usage.md)
+- [Core/Switch - Design](./core-switch--design.md)
+- [Core/Switch - Usage](./core-switch--usage.md)
+- [Core/TabNav - Design](./core-tabnav--design.md)
+- [Core/TabNav - Usage](./core-tabnav--usage.md)
+- [Core/Tag - Design](./core-tag--design.md)
+- [Core/Tag - Usage](./core-tag--usage.md)
+- [Core/Text - Design](./core-text--design.md)
+- [Core/Text - Usage](./core-text--usage.md)
+- [Core/TextArea - Design](./core-textarea--design.md)
+- [Core/TextArea - Usage](./core-textarea--usage.md)
+- [Core/TextField - Design](./core-textfield--design.md)
+- [Core/TextField - Usage](./core-textfield--usage.md)
+- [Core/TextInput - Design](./core-textinput--design.md)
+- [Core/TextInput - Usage](./core-textinput--usage.md)
+- [Core/Toast - Design](./core-toast--design.md)
+- [Core/Toast - Usage](./core-toast--usage.md)
+- [Core/Tooltip - Design](./core-tooltip--design.md)
+- [Core/Tooltip - Usage](./core-tooltip--usage.md)
+- [Core/TopNav - Design](./core-topnav--design.md)
+- [Core/TopNav - Usage](./core-topnav--usage.md)
+- [Core/VerticalNavigation - Design](./core-verticalnavigation--design.md)
+- [Core/VerticalNavigation - Usage](./core-verticalnavigation--usage.md)
+- [Core/VisuallyHidden - Design](./core-visuallyhidden--design.md)
+- [Core/VisuallyHidden - Usage](./core-visuallyhidden--usage.md)
+- [History/Changelogs/@capra-core](./history-changelogs-capra-core--docs.md)

package/docs/using-capra--docs.md

@@ -0,0 +1,39 @@
+# Using Capra
+
+## Installation
+
+Install the Capra packages into your project:
+
+```shell
+pnpm install @capra/core @capra/domain @capra/theme
+```
+
+OR
+
+```shell
+npm install @capra/core @capra/domain @capra/theme
+```
+
+`@capra/theme` is always required. If you are *only* using `@capra/core`, you do not need to install `@capra/domain`.
+
+Prior to importing components, include Capra's CSS in a root stylesheet:
+
+```css
+@import '@capra/theme/base.css';
+@import '@capra/icons/styles.css';
+@import '@capra/core/styles.css';
+```
+
+OR
+
+```less
+@import (inline) '@capra/theme/base.css';
+@import (inline) '@capra/icons/styles.css';
+@import (inline) '@capra/core/styles.css';
+```
+
+:::tip
+
+`@capra/theme/base.css` contains design tokens, font-face rules, and baseline globals. If you only need fonts, import `@capra/theme/fonts.css`. If you only need design tokens, import `@capra/theme/styles.css`.
+
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capra/core",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "description": "Core React components for the Capra design system",
@@ -18,6 +18,7 @@
   "types": "./dist/index.d.mts",
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE.txt"
   ],
@@ -34,7 +35,7 @@
   "dependencies": {
     "react-aria": "^3.48.0",
     "react-aria-components": "^1.17.0",
-    "@capra/icons": "1.6.1"
+    "@capra/icons": "1.7.0"
   },
   "devDependencies": {
     "@ant-design/icons": "4.8.3",
@@ -43,10 +44,10 @@
     "antd": "4.24.16",
     "storybook": "^10.4.6",
     "tsdown": "^0.22.0",
-    "@capra/theme": "1.2.1",
+    "@capra/theme": "1.3.0",
+    "@private/linting": "0.0.0",
     "@private/building": "0.0.4",
     "@private/stories": "0.0.0",
-    "@private/linting": "0.0.0",
     "@private/testing": "0.0.7"
   },
   "scripts": {