@ttoss/fsl-ui 0.2.4

package/dist/tokens/focusRing.mjs

@@ -0,0 +1,28 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { vars } from "@ttoss/fsl-theme/vars";
+
+//#region src/tokens/focusRing.ts
+/**
+* Focus ring resolver — the cross-cutting keyboard-focus outline every
+* interactive component applies per `CONTRACT.md §3`:
+*
+*   - always via `outline` (never `border`) so focus cannot layout-shift;
+*   - always from the cross-cutting `vars.focus.ring.*` tokens (CONTRACT §1
+*     cross-cutting table), never from per-entity color subtrees.
+*
+* Companion to `resolveInteractiveStyle`: that helper owns the state
+* cascade for color dimensions; this one owns the single state-dependent
+* outline. Both exist so components never re-implement state ternaries
+* (structural tokens like radii/spacing stay literal reads by design).
+*/
+/**
+* Returns the `outline` CSS value for the current focus-visible state.
+* Pair with `outlineOffset` at the call site when the component floats the
+* ring off its edge.
+*/
+var focusRingOutline = isFocusVisible => {
+  return isFocusVisible ? `${vars.focus.ring.width} ${vars.focus.ring.style} ${vars.focus.ring.color}` : "none";
+};
+
+//#endregion
+export { focusRingOutline };

package/dist/tokens/keyframes.cjs

@@ -0,0 +1,76 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/tokens/keyframes.ts
+/**
+* Runtime `@keyframes` registry for `@ttoss/fsl-ui`.
+*
+* Components style themselves exclusively through inline styles (no CSS
+* files ship with the package), but CSS animations can only reference
+* `@keyframes` declared in a real stylesheet. This module owns that
+* stylesheet: a single `<style id="fsl-ui-keyframes">` element injected
+* once per document, SSR-safe and idempotent.
+*
+* Rules (enforced by `tests/unit/tests/keyframes.test.ts` and the contract
+* suite):
+*
+* 1. Every animation name used by a component MUST be registered in
+*    `ANIMATION_NAMES` — components reference `ANIMATION_NAMES.*`, never a
+*    bare string.
+* 2. Every registered name MUST have a matching `@keyframes` block in
+*    `KEYFRAMES_CSS`.
+* 3. The stylesheet disables all registered animations under
+*    `prefers-reduced-motion: reduce`.
+*/
+var STYLE_ELEMENT_ID = "fsl-ui-keyframes";
+/**
+* Canonical animation names shipped by the package. Components must
+* reference these constants (never string literals) so the contract test
+* can prove every `animation:` in `src/` resolves to a real `@keyframes`.
+*/
+var ANIMATION_NAMES = {
+  /** Indeterminate ProgressBar fill sweep. */
+  progressBarIndeterminate: "tt-progressbar-indeterminate"
+};
+/**
+* The full stylesheet injected by {@link ensureKeyframes}. Uses logical
+* properties only (`margin-inline-start`) so the sweep direction follows
+* the writing direction under `dir="rtl"`.
+*/
+var KEYFRAMES_CSS = `
+@keyframes ${ANIMATION_NAMES.progressBarIndeterminate} {
+  0% { margin-inline-start: -40%; }
+  100% { margin-inline-start: 100%; }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-scope] [data-part] { animation: none !important; }
+}
+`.trim();
+var injected = false;
+/**
+* Injects the package stylesheet into `document.head` exactly once.
+* No-op on the server (SSR-safe) and when the element already exists
+* (e.g. two copies of the package on one page).
+*
+* Call it from a `React.useInsertionEffect` in any component that uses a
+* name from {@link ANIMATION_NAMES} — insertion effects never run during
+* server rendering, so the SSR guard below is defense in depth for direct
+* callers, not the primary mechanism.
+*/
+var ensureKeyframes = () => {
+  if (injected) return;
+  const doc = globalThis.document;
+  /* istanbul ignore next -- SSR guard: jsdom always provides a document */
+  if (doc === void 0) return;
+  if (doc.getElementById(STYLE_ELEMENT_ID) !== null) {
+    injected = true;
+    return;
+  }
+  const style = doc.createElement("style");
+  style.id = STYLE_ELEMENT_ID;
+  style.textContent = KEYFRAMES_CSS;
+  doc.head.appendChild(style);
+  injected = true;
+};
+
+//#endregion
+exports.ANIMATION_NAMES = ANIMATION_NAMES;
+exports.ensureKeyframes = ensureKeyframes;

package/dist/tokens/keyframes.mjs

@@ -0,0 +1,75 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/tokens/keyframes.ts
+/**
+* Runtime `@keyframes` registry for `@ttoss/fsl-ui`.
+*
+* Components style themselves exclusively through inline styles (no CSS
+* files ship with the package), but CSS animations can only reference
+* `@keyframes` declared in a real stylesheet. This module owns that
+* stylesheet: a single `<style id="fsl-ui-keyframes">` element injected
+* once per document, SSR-safe and idempotent.
+*
+* Rules (enforced by `tests/unit/tests/keyframes.test.ts` and the contract
+* suite):
+*
+* 1. Every animation name used by a component MUST be registered in
+*    `ANIMATION_NAMES` — components reference `ANIMATION_NAMES.*`, never a
+*    bare string.
+* 2. Every registered name MUST have a matching `@keyframes` block in
+*    `KEYFRAMES_CSS`.
+* 3. The stylesheet disables all registered animations under
+*    `prefers-reduced-motion: reduce`.
+*/
+var STYLE_ELEMENT_ID = "fsl-ui-keyframes";
+/**
+* Canonical animation names shipped by the package. Components must
+* reference these constants (never string literals) so the contract test
+* can prove every `animation:` in `src/` resolves to a real `@keyframes`.
+*/
+var ANIMATION_NAMES = {
+  /** Indeterminate ProgressBar fill sweep. */
+  progressBarIndeterminate: "tt-progressbar-indeterminate"
+};
+/**
+* The full stylesheet injected by {@link ensureKeyframes}. Uses logical
+* properties only (`margin-inline-start`) so the sweep direction follows
+* the writing direction under `dir="rtl"`.
+*/
+var KEYFRAMES_CSS = `
+@keyframes ${ANIMATION_NAMES.progressBarIndeterminate} {
+  0% { margin-inline-start: -40%; }
+  100% { margin-inline-start: 100%; }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-scope] [data-part] { animation: none !important; }
+}
+`.trim();
+var injected = false;
+/**
+* Injects the package stylesheet into `document.head` exactly once.
+* No-op on the server (SSR-safe) and when the element already exists
+* (e.g. two copies of the package on one page).
+*
+* Call it from a `React.useInsertionEffect` in any component that uses a
+* name from {@link ANIMATION_NAMES} — insertion effects never run during
+* server rendering, so the SSR guard below is defense in depth for direct
+* callers, not the primary mechanism.
+*/
+var ensureKeyframes = () => {
+  if (injected) return;
+  const doc = globalThis.document;
+  /* istanbul ignore next -- SSR guard: jsdom always provides a document */
+  if (doc === void 0) return;
+  if (doc.getElementById(STYLE_ELEMENT_ID) !== null) {
+    injected = true;
+    return;
+  }
+  const style = doc.createElement("style");
+  style.id = STYLE_ELEMENT_ID;
+  style.textContent = KEYFRAMES_CSS;
+  doc.head.appendChild(style);
+  injected = true;
+};
+
+//#endregion
+export { ANIMATION_NAMES, ensureKeyframes };

package/dist/tokens/resolveInteractiveStyle.cjs

@@ -0,0 +1,41 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+const require_taxonomy = require('../semantics/taxonomy.cjs');
+
+//#region src/tokens/resolveInteractiveStyle.ts
+/**
+* Resolves a single style value from a semantic interactive state object
+* using the canonical cascade defined by `STATE_PRIORITY` in
+* `../semantics/taxonomy`.
+*
+* `STATE_PRIORITY` is the single source of truth for both the **order** of
+* the cascade and the **flag → state-key** mapping. `CONTRACT.md §3`
+* references it by name; this helper iterates it. Order and mapping cannot
+* drift between the contract doc and the implementation because they are
+* derived from the same tuple.
+*
+* The helper is **strict**: when a flag is set, the corresponding state's
+* value is returned as-is (even when `undefined`). Two authoring knobs keep
+* component call sites expressive without re-introducing the copy-pasted
+* ternary chain:
+*
+* - **Omit irrelevant flags** from `flags` to skip that level entirely —
+*   e.g. drop `isFocusVisible` for `background`/`text` dimensions that
+*   never change on focus.
+* - **Apply `?? states.default` at the call site** when fallback to the
+*   resting state is desired (e.g. Button text, where `action.*.text.active`
+*   and `action.*.text.hover` are not always defined on every evaluation).
+*
+* Consumed by `Button`, `Link`, `Checkbox`, `Switch`, `RadioGroup`, `Select`,
+* `TextField`, and `Accordion`.
+*/
+var resolveInteractiveStyle = (states, flags) => {
+  if (!states) return void 0;
+  for (const {
+    flag,
+    state
+  } of require_taxonomy.STATE_PRIORITY) if (flags[flag]) return states[state];
+  return states.default;
+};
+
+//#endregion
+exports.resolveInteractiveStyle = resolveInteractiveStyle;

package/dist/tokens/resolveInteractiveStyle.mjs

@@ -0,0 +1,41 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { STATE_PRIORITY } from "../semantics/taxonomy.mjs";
+
+//#region src/tokens/resolveInteractiveStyle.ts
+/**
+* Resolves a single style value from a semantic interactive state object
+* using the canonical cascade defined by `STATE_PRIORITY` in
+* `../semantics/taxonomy`.
+*
+* `STATE_PRIORITY` is the single source of truth for both the **order** of
+* the cascade and the **flag → state-key** mapping. `CONTRACT.md §3`
+* references it by name; this helper iterates it. Order and mapping cannot
+* drift between the contract doc and the implementation because they are
+* derived from the same tuple.
+*
+* The helper is **strict**: when a flag is set, the corresponding state's
+* value is returned as-is (even when `undefined`). Two authoring knobs keep
+* component call sites expressive without re-introducing the copy-pasted
+* ternary chain:
+*
+* - **Omit irrelevant flags** from `flags` to skip that level entirely —
+*   e.g. drop `isFocusVisible` for `background`/`text` dimensions that
+*   never change on focus.
+* - **Apply `?? states.default` at the call site** when fallback to the
+*   resting state is desired (e.g. Button text, where `action.*.text.active`
+*   and `action.*.text.hover` are not always defined on every evaluation).
+*
+* Consumed by `Button`, `Link`, `Checkbox`, `Switch`, `RadioGroup`, `Select`,
+* `TextField`, and `Accordion`.
+*/
+var resolveInteractiveStyle = (states, flags) => {
+  if (!states) return void 0;
+  for (const {
+    flag,
+    state
+  } of STATE_PRIORITY) if (flags[flag]) return states[state];
+  return states.default;
+};
+
+//#endregion
+export { resolveInteractiveStyle };

package/llms.txt

@@ -0,0 +1,142 @@
+# @ttoss/fsl-ui
+
+Semantic, token-native React component library. Built on React Aria
+Components; styled exclusively with `@ttoss/fsl-theme` CSS-variable tokens.
+Every component declares a formal semantic identity (FSL — Foundational
+Semantic Language) that determines which tokens it may consume.
+
+Ground truth in the published package: `src/tokens/CONTRACT.md` (full Layer-2
+contract). This file is the distilled, machine-oriented summary.
+
+## Setup
+
+```tsx
+import { createTheme } from '@ttoss/fsl-theme';
+import { ThemeProvider } from '@ttoss/fsl-theme/react';
+import { Button } from '@ttoss/fsl-ui';
+
+const theme = createTheme(); // base theme + dark alternate
+
+<ThemeProvider theme={theme} defaultMode="system">
+  <Button evaluation="primary" onPress={save}>Save</Button>
+</ThemeProvider>
+```
+
+Without a ThemeProvider (or ThemeHead/ThemeScript on SSR) the CSS variables
+are undefined and components render unstyled.
+
+## Semantic model (what the props mean)
+
+- entity — what the component IS (fixed per component, not a prop):
+  Action, Input, Selection, Navigation, Disclosure, Overlay, Feedback,
+  Collection, Structure.
+- evaluation (prop) — AUTHORIAL emphasis, chosen when writing the UI:
+  e.g. 'primary' | 'secondary' | 'accent' | 'muted' | 'negative' on Action.
+  Input/Selection components have NO evaluation prop (data entry carries no
+  authorial voice); validation is the runtime `invalid` STATE (`isInvalid`),
+  never `evaluation="negative"`.
+- consequence (prop) — effect on state: 'neutral' | 'committing' |
+  'destructive'. Drives MECHANISM (e.g. ConfirmationDialog two-click arming),
+  not color. Destructive ≠ negative color; pair them explicitly if desired.
+- composition (prop on leaves) — slot the element plays inside a parent:
+  'primaryAction' | 'secondaryAction' | 'dismissAction' … DialogActions
+  reorders children by it per platform convention.
+- State — runtime only (hover, active, focused, disabled, checked,
+  indeterminate, expanded, invalid, …). Emitted by React Aria render props;
+  priority cascade: disabled > invalid > expanded > indeterminate >
+  selected > focusVisible > pressed > hovered > default.
+
+## Component catalog (all exports also ship a `*Meta` identity object)
+
+Action:      Button, ToggleButton, FileTrigger (opens OS file picker),
+             MenuItem (inside Menu), FormSubmit (inside Form)
+Navigation:  Link, Breadcrumbs/Breadcrumb, Tabs/TabList/Tab
+             (TabPanel is Structure — the content revealed by the tabs)
+Disclosure:  Accordion, AccordionItem, AccordionTrigger, AccordionPanel,
+             Disclosure, DisclosureTrigger, DisclosurePanel (standalone single
+             section — Accordion is the DisclosureGroup)
+Selection:   Checkbox, CheckboxGroup, RadioGroup/Radio, Switch,
+             Select/SelectItem, ToggleButtonGroup, TagGroup/Tag
+             (CheckboxGroup group-level isInvalid propagates to child Checkboxes;
+             its label part is Selection/label, but description + validationMessage
+             are internal parts — Selection has no such structural roles.
+             TagGroup/Tag: a chosen tag uses the `selected` State, NOT `pressed`
+             — a tag is set membership, not a toggle; remove button is an
+             internal closeTrigger part (not a Selection role))
+Collection:  ListBox/ListBoxItem, GridList/GridListItem (+ Menu/MenuItem,
+             listed under Overlay for its popover surface). ADR-007: the
+             CONTAINER is Collection (informational surface) but selectable
+             ITEMS are Selection (input chrome, `selected` State) — one
+             composite, two entities. GridListItem also has a selectionControl
+             (per-row checkbox).
+Input:       TextField, TextArea (each + Label/Control/Description/Error),
+             SearchField (+ Label/Control; leading search + clear glyphs),
+             NumberField (label/description/errorMessage props + −/+ steppers),
+             Slider (label + value output; single value or [min,max] range)
+Overlay:     Dialog, DialogModal, DialogTrigger, DialogHeading, DialogBody,
+             DialogActions, Menu, MenuTrigger, ConfirmationDialog,
+             Popover, PopoverTrigger, Tooltip, TooltipTrigger
+Feedback:    ProgressBar, Meter, Toast, ToastRegion, createToastQueue
+             (Meter = static quantity in a range e.g. battery/disk;
+             ProgressBar = a task in flight. Pick by "state" vs "progressing")
+Structure:   Form, FormActions, Wizard, WizardStep, WizardSummary,
+             WizardNavigation, Separator, Group (labelled role=group frame),
+             Toolbar (role=toolbar, arrow-key roving nav over its controls)
+
+Icons: INTERNAL only (not exported). Components render glyphs through an
+internal semantic Icon layer (`src/components/Icon/`) that maps `icon.{family}.{intent}`
+intents to Lucide glyphs via the Iconify provider (`@iconify-icon/react`),
+registered offline (no runtime API fetch). Future standalone `@ttoss/fsl-icon`.
+See CONTRIBUTING ADR-005.
+
+## Entity → token map (a component reads ONLY its row)
+
+Action      → colors.action,        radii.control, motion.feedback
+Input       → colors.input,         radii.control, motion.feedback
+Selection   → colors.input,         radii.control, motion.feedback
+Navigation  → colors.navigation,    radii.control, motion.feedback
+Disclosure  → colors.navigation,    radii.control, motion.transition
+Overlay     → colors.informational, radii.surface, motion.transition, elevation.overlay
+Feedback    → colors.feedback,      radii.surface, elevation.raised
+Collection  → colors.informational, radii.surface
+Structure   → colors.informational, radii.surface
+
+Color path formula: `vars.colors.{ux}[evaluation][background|border|text][state]`
+→ CSS var `--tt-colors-{ux}-{evaluation}-{dimension}-{state}`.
+
+## Rules an integrating agent must follow
+
+1. Composites accept NO `style`/`className`. Customize geometry via CSS
+   custom-property knobs on the composite scope (fallbacks built in):
+   `--fsl-dialog-max-width` (default min(500px, 90vw)),
+   `--fsl-dialog-max-height` (90vh), `--fsl-menu-min-width` (12rem),
+   `--fsl-menu-max-width` (min(320px, 90vw)),
+   `--fsl-popover-max-width` (min(320px, 90vw)),
+   `--fsl-tooltip-max-width` (min(280px, 90vw)).
+   Example: `[data-scope='dialog'] { --fsl-dialog-max-width: 720px; }`
+2. There is NO `size` prop anywhere. Different density = different
+   semantic identity = different component.
+3. i18n: flow-critical labels are REQUIRED props with no defaults —
+   ConfirmationDialog (confirmLabel, cancelLabel, armedLabel when
+   consequence="destructive") and WizardNavigation (prevLabel, nextLabel,
+   finishLabel). Supply localized copy from the host app.
+4. Validation: pass `isInvalid` (or React Aria `validate`) — never a color
+   prop. Invalid styling comes from `input.*.{dimension}.invalid` tokens.
+5. Destructive confirms: `<ConfirmationDialog consequence="destructive">`
+   requires TWO clicks (arming). `consequence="committing"` +
+   `evaluation="negative"` gives a red one-click confirm.
+6. Every element exposes `data-scope`/`data-part` (plus `data-evaluation`,
+   `data-consequence`, `data-composition`, `data-arming` where relevant) —
+   use these for CSS targeting and tests; never rely on internal class names.
+7. All layout is logical-property based (RTL-safe); keep host CSS logical too.
+
+## Package facts
+
+- ESM only, `sideEffects: false`, tree-shakes (Button-only import ≈ 1.8 KB
+  min before deps). Peer deps: react >= 18, react-dom >= 18.
+- `react-aria-components` pinned `~1.19.0` while Toast uses UNSTABLE_ APIs.
+- SSR-safe: the only DOM injection (`@keyframes` for ProgressBar) happens in
+  a client-only insertion effect. Icon glyphs register into an in-memory
+  Iconify registry (no DOM, no network), so they are SSR-safe too.
+- Icons: Iconify (`@iconify-icon/react`) is the official glyph provider;
+  default set is Lucide (`@iconify/icons-lucide`, per-icon / tree-shakeable).

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@ttoss/fsl-ui",
+  "version": "0.2.4",
+  "description": "Semantic, token-native component library for the ttoss ecosystem. Built on React Aria Components with @ttoss/fsl-theme tokens.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/fsl-ui"
+  },
+  "license": "MIT",
+  "author": "Ennio Lopes <enniolopes@gmail.com>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module": "./dist/index.mjs",
+      "browser": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./semantics": {
+      "types": "./dist/semantics/index.d.mts",
+      "default": "./dist/semantics/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "src/tokens/CONTRACT.md"
+  ],
+  "dependencies": {
+    "@iconify-icon/react": "^2.2.0",
+    "@iconify/icons-lucide": "^1.2.135",
+    "react-aria-components": "~1.19.0",
+    "@ttoss/fsl-theme": "^2.1.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest-axe": "^3.5.9",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.0.2",
+    "esbuild": "^0.28.0",
+    "jest": "^30.4.2",
+    "jest-axe": "^10.0.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-hook-form": "^7.71.1",
+    "tsdown": "^0.22.2",
+    "zod": "^4.4.3",
+    "@ttoss/test-utils": "^4.2.18",
+    "@ttoss/config": "^1.37.17",
+    "@ttoss/forms": "^0.44.4"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "tsc --noEmit -p tsconfig.json && jest --projects tests/unit",
+    "verify:treeshake": "node scripts/verify-treeshake.mjs"
+  }
+}