@ttoss/fsl-ui 0.2.4 → 0.2.6

package/README.md

@@ -59,7 +59,7 @@ Composites accept no `style`/`className`. Geometry the host legitimately owns is
 
 The registered knobs and the full policy live in `src/tokens/CONTRACT.md` §7.
 
-Icons are internal: components render glyphs through a semantic layer over the [Iconify](https://iconify.design/) provider (default set: Lucide), registered offline (no runtime network fetch). There is no public `Icon` export yet — see CONTRIBUTING ADR-005.
+Icons are semantic: `Icon` (public since ADR-010) is named by intent (`<Icon intent="status.success" />`), never by glyph. The theme maps intents to [Iconify](https://iconify.design/) glyphs (default set: Lucide), registered offline (no runtime network fetch); color inherits via `currentColor` and size comes from `vars.sizing.icon.*`.
 
 ## AI-first surface
 

package/dist/components/AppShell/AppShell.cjs

@@ -0,0 +1,124 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/components/AppShell/AppShell.tsx
+/** Formal semantic identity — AppShell root (Structure entity, app frame). */
+var appShellMeta = {
+  displayName: "AppShell",
+  entity: "Structure",
+  structure: "root"
+};
+var SIDEBAR_WIDTH = {
+  sm: "13rem",
+  md: "16rem",
+  lg: "20rem"
+};
+/** Build the body's column template from which side panels are present. */
+var bodyColumns = ({
+  hasSidebar,
+  hasAside,
+  sidebarWidth,
+  asideWidth
+}) => {
+  return `${hasSidebar ? `${SIDEBAR_WIDTH[sidebarWidth]} ` : ""}minmax(0, 1fr)${hasAside ? ` ${SIDEBAR_WIDTH[asideWidth]}` : ""}`;
+};
+var HAIRLINE = `${_ttoss_fsl_theme_vars.vars.border.outline.surface.width} ${_ttoss_fsl_theme_vars.vars.border.outline.surface.style} ${_ttoss_fsl_theme_vars.vars.colors.informational.muted.border?.default}`;
+/**
+* The application-frame primitive — a full-viewport header + sidebars + main.
+*
+* Entity = Structure. Wrap the whole app in an AppShell to get the standard
+* "header over navigator | main | inspector" frame without hand-rolling a grid:
+* pass any of `header`, `sidebar`, `aside`, and the main content as `children`.
+* The frame fills the viewport, each region scrolls on its own, and the main
+* region always takes the remaining width. Sidebar widths come from a named
+* scale — there is no raw track template.
+*
+* @example
+* ```tsx
+* <AppShell
+*   header={<Toolbar>…</Toolbar>}
+*   sidebar={<Navigator />}
+*   aside={<Inspector />}
+* >
+*   <MainStage />
+* </AppShell>
+* ```
+*/
+var AppShell = ({
+  header,
+  sidebar,
+  aside,
+  sidebarWidth = "sm",
+  asideWidth = "sm",
+  sidebarLabel,
+  asideLabel,
+  children,
+  ...props
+}) => {
+  const hasSidebar = sidebar !== void 0 && sidebar !== null;
+  const hasAside = aside !== void 0 && aside !== null;
+  return /* @__PURE__ */(0, react_jsx_runtime.jsxs)("div", {
+    ...props,
+    "data-scope": "app-shell",
+    "data-part": "root",
+    style: {
+      display: "grid",
+      gridTemplateRows: header ? "auto minmax(0, 1fr)" : "minmax(0, 1fr)",
+      blockSize: "100dvh"
+    },
+    children: [header ? /* @__PURE__ */(0, react_jsx_runtime.jsx)("header", {
+      "data-scope": "app-shell",
+      "data-part": "header",
+      style: {
+        borderBlockEnd: HAIRLINE
+      },
+      children: header
+    }) : null, /* @__PURE__ */(0, react_jsx_runtime.jsxs)("div", {
+      "data-scope": "app-shell",
+      "data-part": "body",
+      style: {
+        display: "grid",
+        gridTemplateColumns: bodyColumns({
+          hasSidebar,
+          hasAside,
+          sidebarWidth,
+          asideWidth
+        }),
+        minBlockSize: 0
+      },
+      children: [hasSidebar ? /* @__PURE__ */(0, react_jsx_runtime.jsx)("aside", {
+        "data-scope": "app-shell",
+        "data-part": "sidebar",
+        "aria-label": sidebarLabel,
+        style: {
+          overflowY: "auto",
+          borderInlineEnd: HAIRLINE
+        },
+        children: sidebar
+      }) : null, /* @__PURE__ */(0, react_jsx_runtime.jsx)("main", {
+        "data-scope": "app-shell",
+        "data-part": "main",
+        style: {
+          overflow: "auto",
+          minInlineSize: 0
+        },
+        children
+      }), hasAside ? /* @__PURE__ */(0, react_jsx_runtime.jsx)("aside", {
+        "data-scope": "app-shell",
+        "data-part": "aside",
+        "aria-label": asideLabel,
+        style: {
+          overflowY: "auto",
+          borderInlineStart: HAIRLINE
+        },
+        children: aside
+      }) : null]
+    })]
+  });
+};
+AppShell.displayName = appShellMeta.displayName;
+
+//#endregion
+exports.AppShell = AppShell;
+exports.appShellMeta = appShellMeta;

package/dist/components/AppShell/AppShell.d.cts

@@ -0,0 +1,74 @@
+
+import * as React from "react";
+
+//#region src/components/AppShell/AppShell.d.ts
+/** Formal semantic identity — AppShell root (Structure entity, app frame). */
+declare const appShellMeta: {
+  readonly displayName: "AppShell";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/** Sidebar width from a named threshold scale (not a raw length). */
+type AppShellSidebarWidth = 'sm' | 'md' | 'lg';
+/** Props for the AppShell component. */
+interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /** Top bar, spanning the full width above the body. Omit for no header. */
+  header?: React.ReactNode;
+  /** Start-side panel (navigator). Omit for no start sidebar. */
+  sidebar?: React.ReactNode;
+  /** End-side panel (inspector). Omit for no end aside. */
+  aside?: React.ReactNode;
+  /**
+   * Width of the start `sidebar`, from the named scale.
+   * @default 'sm'
+   */
+  sidebarWidth?: AppShellSidebarWidth;
+  /**
+   * Width of the end `aside`, from the named scale.
+   * @default 'sm'
+   */
+  asideWidth?: AppShellSidebarWidth;
+  /** Accessible name for the start `sidebar` landmark (`aria-label`). */
+  sidebarLabel?: string;
+  /** Accessible name for the end `aside` landmark (`aria-label`). */
+  asideLabel?: string;
+  /** The main region — always takes the remaining space and scrolls. */
+  children?: React.ReactNode;
+}
+/**
+ * The application-frame primitive — a full-viewport header + sidebars + main.
+ *
+ * Entity = Structure. Wrap the whole app in an AppShell to get the standard
+ * "header over navigator | main | inspector" frame without hand-rolling a grid:
+ * pass any of `header`, `sidebar`, `aside`, and the main content as `children`.
+ * The frame fills the viewport, each region scrolls on its own, and the main
+ * region always takes the remaining width. Sidebar widths come from a named
+ * scale — there is no raw track template.
+ *
+ * @example
+ * ```tsx
+ * <AppShell
+ *   header={<Toolbar>…</Toolbar>}
+ *   sidebar={<Navigator />}
+ *   aside={<Inspector />}
+ * >
+ *   <MainStage />
+ * </AppShell>
+ * ```
+ */
+declare const AppShell: {
+  ({
+    header,
+    sidebar,
+    aside,
+    sidebarWidth,
+    asideWidth,
+    sidebarLabel,
+    asideLabel,
+    children,
+    ...props
+  }: AppShellProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "AppShell";
+};
+//#endregion
+export { AppShell, AppShellProps, AppShellSidebarWidth, appShellMeta };

package/dist/components/AppShell/AppShell.d.mts

@@ -0,0 +1,74 @@
+
+import * as React from "react";
+
+//#region src/components/AppShell/AppShell.d.ts
+/** Formal semantic identity — AppShell root (Structure entity, app frame). */
+declare const appShellMeta: {
+  readonly displayName: "AppShell";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/** Sidebar width from a named threshold scale (not a raw length). */
+type AppShellSidebarWidth = 'sm' | 'md' | 'lg';
+/** Props for the AppShell component. */
+interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /** Top bar, spanning the full width above the body. Omit for no header. */
+  header?: React.ReactNode;
+  /** Start-side panel (navigator). Omit for no start sidebar. */
+  sidebar?: React.ReactNode;
+  /** End-side panel (inspector). Omit for no end aside. */
+  aside?: React.ReactNode;
+  /**
+   * Width of the start `sidebar`, from the named scale.
+   * @default 'sm'
+   */
+  sidebarWidth?: AppShellSidebarWidth;
+  /**
+   * Width of the end `aside`, from the named scale.
+   * @default 'sm'
+   */
+  asideWidth?: AppShellSidebarWidth;
+  /** Accessible name for the start `sidebar` landmark (`aria-label`). */
+  sidebarLabel?: string;
+  /** Accessible name for the end `aside` landmark (`aria-label`). */
+  asideLabel?: string;
+  /** The main region — always takes the remaining space and scrolls. */
+  children?: React.ReactNode;
+}
+/**
+ * The application-frame primitive — a full-viewport header + sidebars + main.
+ *
+ * Entity = Structure. Wrap the whole app in an AppShell to get the standard
+ * "header over navigator | main | inspector" frame without hand-rolling a grid:
+ * pass any of `header`, `sidebar`, `aside`, and the main content as `children`.
+ * The frame fills the viewport, each region scrolls on its own, and the main
+ * region always takes the remaining width. Sidebar widths come from a named
+ * scale — there is no raw track template.
+ *
+ * @example
+ * ```tsx
+ * <AppShell
+ *   header={<Toolbar>…</Toolbar>}
+ *   sidebar={<Navigator />}
+ *   aside={<Inspector />}
+ * >
+ *   <MainStage />
+ * </AppShell>
+ * ```
+ */
+declare const AppShell: {
+  ({
+    header,
+    sidebar,
+    aside,
+    sidebarWidth,
+    asideWidth,
+    sidebarLabel,
+    asideLabel,
+    children,
+    ...props
+  }: AppShellProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "AppShell";
+};
+//#endregion
+export { AppShell, AppShellProps, AppShellSidebarWidth, appShellMeta };

package/dist/components/AppShell/AppShell.mjs

@@ -0,0 +1,123 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { vars } from "@ttoss/fsl-theme/vars";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/components/AppShell/AppShell.tsx
+/** Formal semantic identity — AppShell root (Structure entity, app frame). */
+var appShellMeta = {
+  displayName: "AppShell",
+  entity: "Structure",
+  structure: "root"
+};
+var SIDEBAR_WIDTH = {
+  sm: "13rem",
+  md: "16rem",
+  lg: "20rem"
+};
+/** Build the body's column template from which side panels are present. */
+var bodyColumns = ({
+  hasSidebar,
+  hasAside,
+  sidebarWidth,
+  asideWidth
+}) => {
+  return `${hasSidebar ? `${SIDEBAR_WIDTH[sidebarWidth]} ` : ""}minmax(0, 1fr)${hasAside ? ` ${SIDEBAR_WIDTH[asideWidth]}` : ""}`;
+};
+var HAIRLINE = `${vars.border.outline.surface.width} ${vars.border.outline.surface.style} ${vars.colors.informational.muted.border?.default}`;
+/**
+* The application-frame primitive — a full-viewport header + sidebars + main.
+*
+* Entity = Structure. Wrap the whole app in an AppShell to get the standard
+* "header over navigator | main | inspector" frame without hand-rolling a grid:
+* pass any of `header`, `sidebar`, `aside`, and the main content as `children`.
+* The frame fills the viewport, each region scrolls on its own, and the main
+* region always takes the remaining width. Sidebar widths come from a named
+* scale — there is no raw track template.
+*
+* @example
+* ```tsx
+* <AppShell
+*   header={<Toolbar>…</Toolbar>}
+*   sidebar={<Navigator />}
+*   aside={<Inspector />}
+* >
+*   <MainStage />
+* </AppShell>
+* ```
+*/
+var AppShell = ({
+  header,
+  sidebar,
+  aside,
+  sidebarWidth = "sm",
+  asideWidth = "sm",
+  sidebarLabel,
+  asideLabel,
+  children,
+  ...props
+}) => {
+  const hasSidebar = sidebar !== void 0 && sidebar !== null;
+  const hasAside = aside !== void 0 && aside !== null;
+  return /* @__PURE__ */jsxs("div", {
+    ...props,
+    "data-scope": "app-shell",
+    "data-part": "root",
+    style: {
+      display: "grid",
+      gridTemplateRows: header ? "auto minmax(0, 1fr)" : "minmax(0, 1fr)",
+      blockSize: "100dvh"
+    },
+    children: [header ? /* @__PURE__ */jsx("header", {
+      "data-scope": "app-shell",
+      "data-part": "header",
+      style: {
+        borderBlockEnd: HAIRLINE
+      },
+      children: header
+    }) : null, /* @__PURE__ */jsxs("div", {
+      "data-scope": "app-shell",
+      "data-part": "body",
+      style: {
+        display: "grid",
+        gridTemplateColumns: bodyColumns({
+          hasSidebar,
+          hasAside,
+          sidebarWidth,
+          asideWidth
+        }),
+        minBlockSize: 0
+      },
+      children: [hasSidebar ? /* @__PURE__ */jsx("aside", {
+        "data-scope": "app-shell",
+        "data-part": "sidebar",
+        "aria-label": sidebarLabel,
+        style: {
+          overflowY: "auto",
+          borderInlineEnd: HAIRLINE
+        },
+        children: sidebar
+      }) : null, /* @__PURE__ */jsx("main", {
+        "data-scope": "app-shell",
+        "data-part": "main",
+        style: {
+          overflow: "auto",
+          minInlineSize: 0
+        },
+        children
+      }), hasAside ? /* @__PURE__ */jsx("aside", {
+        "data-scope": "app-shell",
+        "data-part": "aside",
+        "aria-label": asideLabel,
+        style: {
+          overflowY: "auto",
+          borderInlineStart: HAIRLINE
+        },
+        children: aside
+      }) : null]
+    })]
+  });
+};
+AppShell.displayName = appShellMeta.displayName;
+
+//#endregion
+export { AppShell, appShellMeta };

package/dist/components/Badge/Badge.cjs

@@ -0,0 +1,61 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/components/Badge/Badge.tsx
+/** Formal semantic identity — Badge root (Feedback entity, status pill). */
+var badgeMeta = {
+  displayName: "Badge",
+  entity: "Feedback",
+  structure: "root"
+};
+/**
+* A compact status pill bound to the FSL feedback palette.
+*
+* Entity = Feedback. Use it for a small, non-interactive tag whose colour
+* carries meaning: a contrast rating, a validation state, a count. Pick the
+* `evaluation` by valence, not by colour — the theme decides the hue per mode.
+* For running feedback messages use `Toast`; for interactive filters use a
+* control.
+*
+* @example
+* ```tsx
+* <Badge evaluation="positive" numeric="tabular">AA 5.1:1</Badge>
+* <Badge evaluation="negative">Fail</Badge>
+* ```
+*/
+var Badge = ({
+  evaluation = "primary",
+  numeric = "normal",
+  children,
+  ...props
+}) => {
+  const colors = _ttoss_fsl_theme_vars.vars.colors.feedback[evaluation];
+  return /* @__PURE__ */(0, react_jsx_runtime.jsx)("span", {
+    ...props,
+    "data-scope": "badge",
+    "data-part": "root",
+    "data-evaluation": evaluation,
+    style: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      paddingBlock: _ttoss_fsl_theme_vars.vars.spacing.inset.control.sm,
+      paddingInline: _ttoss_fsl_theme_vars.vars.spacing.inset.control.md,
+      borderRadius: _ttoss_fsl_theme_vars.vars.radii.control,
+      borderWidth: _ttoss_fsl_theme_vars.vars.border.outline.surface.width,
+      borderStyle: _ttoss_fsl_theme_vars.vars.border.outline.surface.style,
+      borderColor: colors?.border?.default,
+      color: colors?.text?.default,
+      backgroundColor: colors?.background?.default,
+      fontVariantNumeric: numeric === "tabular" ? "tabular-nums" : void 0,
+      ..._ttoss_fsl_theme_vars.vars.text.label.sm
+    },
+    children
+  });
+};
+Badge.displayName = badgeMeta.displayName;
+
+//#endregion
+exports.Badge = Badge;
+exports.badgeMeta = badgeMeta;

package/dist/components/Badge/Badge.d.cts

@@ -0,0 +1,56 @@
+
+import { EvaluationsFor } from "../../semantics/taxonomy.cjs";
+import * as React from "react";
+
+//#region src/components/Badge/Badge.d.ts
+/** Formal semantic identity — Badge root (Feedback entity, status pill). */
+declare const badgeMeta: {
+  readonly displayName: "Badge";
+  readonly entity: "Feedback";
+  readonly structure: "root";
+};
+/** Numeric figure style — `tabular` aligns digits (ratios, counts). */
+type BadgeNumeric = 'normal' | 'tabular';
+/** Props for the Badge component. */
+interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style' | 'className'> {
+  /**
+   * Feedback valence the badge communicates. `primary` is neutral-informational;
+   * `positive`/`caution`/`negative` carry status colour.
+   * @default 'primary'
+   */
+  evaluation?: EvaluationsFor<(typeof badgeMeta)['entity']>;
+  /**
+   * Numeric figure style. `tabular` renders `tabular-nums` so digits line up —
+   * use it for ratios/counts inside a scannable column.
+   * @default 'normal'
+   */
+  numeric?: BadgeNumeric;
+  /** The badge label. */
+  children?: React.ReactNode;
+}
+/**
+ * A compact status pill bound to the FSL feedback palette.
+ *
+ * Entity = Feedback. Use it for a small, non-interactive tag whose colour
+ * carries meaning: a contrast rating, a validation state, a count. Pick the
+ * `evaluation` by valence, not by colour — the theme decides the hue per mode.
+ * For running feedback messages use `Toast`; for interactive filters use a
+ * control.
+ *
+ * @example
+ * ```tsx
+ * <Badge evaluation="positive" numeric="tabular">AA 5.1:1</Badge>
+ * <Badge evaluation="negative">Fail</Badge>
+ * ```
+ */
+declare const Badge: {
+  ({
+    evaluation,
+    numeric,
+    children,
+    ...props
+  }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Badge";
+};
+//#endregion
+export { Badge, BadgeNumeric, BadgeProps, badgeMeta };

package/dist/components/Badge/Badge.d.mts

@@ -0,0 +1,56 @@
+
+import { EvaluationsFor } from "../../semantics/taxonomy.mjs";
+import * as React from "react";
+
+//#region src/components/Badge/Badge.d.ts
+/** Formal semantic identity — Badge root (Feedback entity, status pill). */
+declare const badgeMeta: {
+  readonly displayName: "Badge";
+  readonly entity: "Feedback";
+  readonly structure: "root";
+};
+/** Numeric figure style — `tabular` aligns digits (ratios, counts). */
+type BadgeNumeric = 'normal' | 'tabular';
+/** Props for the Badge component. */
+interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style' | 'className'> {
+  /**
+   * Feedback valence the badge communicates. `primary` is neutral-informational;
+   * `positive`/`caution`/`negative` carry status colour.
+   * @default 'primary'
+   */
+  evaluation?: EvaluationsFor<(typeof badgeMeta)['entity']>;
+  /**
+   * Numeric figure style. `tabular` renders `tabular-nums` so digits line up —
+   * use it for ratios/counts inside a scannable column.
+   * @default 'normal'
+   */
+  numeric?: BadgeNumeric;
+  /** The badge label. */
+  children?: React.ReactNode;
+}
+/**
+ * A compact status pill bound to the FSL feedback palette.
+ *
+ * Entity = Feedback. Use it for a small, non-interactive tag whose colour
+ * carries meaning: a contrast rating, a validation state, a count. Pick the
+ * `evaluation` by valence, not by colour — the theme decides the hue per mode.
+ * For running feedback messages use `Toast`; for interactive filters use a
+ * control.
+ *
+ * @example
+ * ```tsx
+ * <Badge evaluation="positive" numeric="tabular">AA 5.1:1</Badge>
+ * <Badge evaluation="negative">Fail</Badge>
+ * ```
+ */
+declare const Badge: {
+  ({
+    evaluation,
+    numeric,
+    children,
+    ...props
+  }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Badge";
+};
+//#endregion
+export { Badge, BadgeNumeric, BadgeProps, badgeMeta };

package/dist/components/Badge/Badge.mjs

@@ -0,0 +1,60 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { vars } from "@ttoss/fsl-theme/vars";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/Badge/Badge.tsx
+/** Formal semantic identity — Badge root (Feedback entity, status pill). */
+var badgeMeta = {
+  displayName: "Badge",
+  entity: "Feedback",
+  structure: "root"
+};
+/**
+* A compact status pill bound to the FSL feedback palette.
+*
+* Entity = Feedback. Use it for a small, non-interactive tag whose colour
+* carries meaning: a contrast rating, a validation state, a count. Pick the
+* `evaluation` by valence, not by colour — the theme decides the hue per mode.
+* For running feedback messages use `Toast`; for interactive filters use a
+* control.
+*
+* @example
+* ```tsx
+* <Badge evaluation="positive" numeric="tabular">AA 5.1:1</Badge>
+* <Badge evaluation="negative">Fail</Badge>
+* ```
+*/
+var Badge = ({
+  evaluation = "primary",
+  numeric = "normal",
+  children,
+  ...props
+}) => {
+  const colors = vars.colors.feedback[evaluation];
+  return /* @__PURE__ */jsx("span", {
+    ...props,
+    "data-scope": "badge",
+    "data-part": "root",
+    "data-evaluation": evaluation,
+    style: {
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      paddingBlock: vars.spacing.inset.control.sm,
+      paddingInline: vars.spacing.inset.control.md,
+      borderRadius: vars.radii.control,
+      borderWidth: vars.border.outline.surface.width,
+      borderStyle: vars.border.outline.surface.style,
+      borderColor: colors?.border?.default,
+      color: colors?.text?.default,
+      backgroundColor: colors?.background?.default,
+      fontVariantNumeric: numeric === "tabular" ? "tabular-nums" : void 0,
+      ...vars.text.label.sm
+    },
+    children
+  });
+};
+Badge.displayName = badgeMeta.displayName;
+
+//#endregion
+export { Badge, badgeMeta };