@dashforge/tw 1.7.0 → 2.0.0

package/dist/{src/components → components}/Grid/grid.types.d.ts

@@ -1,4 +1,6 @@
 import type { ElementType, HTMLAttributes } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
 /**
  * Grid types — discriminated union for container vs item role.
  *
@@ -94,6 +96,46 @@ interface GridCommonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'classNam
     asChild?: boolean;
     /** Utility-class override, merged via tailwind-merge. */
     sx?: string;
+    /**
+     * Reactive visibility predicate. When it returns `false` the component
+     * renders `null`. Inside a `<DashForm>` it subscribes reactively to
+     * engine state; outside a form it is evaluated as a plain closure.
+     *
+     * Use it for state-driven hiding. **For permission-driven hiding prefer
+     * `access` with `onUnauthorized: 'hide'`**, which is the semantically
+     * correct path and surfaces properly in RBAC dev tools.
+     *
+     * @default undefined
+     *
+     * @example
+     * ```tsx
+     * <Grid visibleWhen={() => pendingCount > 0}>
+     *   <Typography variant="h3">{pendingCount} pending</Typography>
+     * </Grid>
+     * ```
+     */
+    visibleWhen?: (engine: Engine) => boolean;
+    /**
+     * RBAC requirement, evaluated by the centralized `@dashforge/rbac`
+     * policy engine. Brings Grid to parity with `<Box>`, which has
+     * carried both props since 1.1.0.
+     *
+     * - `onUnauthorized: 'hide'`     → does not render
+     * - `onUnauthorized: 'disable'`  → `aria-disabled` + dimmed; interactive
+     *   children derive their own state from `data-disabled` or carry their
+     *   own `access`
+     * - `onUnauthorized: 'readonly'` → `aria-readonly`, for gated sections
+     *
+     * @default undefined
+     *
+     * @example
+     * ```tsx
+     * <Grid access={{ resource: 'billing', action: 'read', onUnauthorized: 'hide' }}>
+     *   <RevenueCard />
+     * </Grid>
+     * ```
+     */
+    access?: AccessRequirement;
 }
 /**
  * `<Grid>` props — discriminated union: container OR item, never both.

package/dist/components/Kbd/Kbd.d.ts

@@ -0,0 +1,13 @@
+import type { KbdProps } from './kbd.types.js';
+/**
+ * `<Kbd>` — a single keycap.
+ *
+ * ```tsx
+ * Press <Kbd>Esc</Kbd> to close
+ * ```
+ *
+ * See {@link KbdProps} for the full API surface, including why chords are
+ * composed rather than passed as an array.
+ */
+export declare const Kbd: import("react").ForwardRefExoticComponent<KbdProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=Kbd.d.ts.map

package/dist/components/Kbd/kbd.types.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react';
+import type { KbdVariants } from './kbd.variants.js';
+/** Size scale. `md` matches body text; `sm` sits inside dense chrome. */
+export type KbdSize = NonNullable<KbdVariants['size']>;
+/**
+ * Subset of `<Kbd>` props configurable through
+ * `theme.components.Kbd.defaults` (Option C).
+ */
+export type KbdVariantProps = Pick<KbdVariants, 'size'>;
+/**
+ * Props for `<Kbd>` — a single keycap, for showing the key that triggers
+ * something (`⌘K`, `Esc`, `Shift`).
+ *
+ * It renders the semantic `<kbd>` element rather than a styled span, which
+ * is the whole reason the primitive exists: assistive tech and reader modes
+ * treat `<kbd>` as keyboard input, and a span says nothing.
+ *
+ * **Combinations compose.** There is no `keys` prop: a chord is two caps
+ * and whatever separator the design calls for, and baking one in would
+ * decide `⌘ + K` against `⌘K` for every consumer.
+ *
+ * ```tsx
+ * <span className="inline-flex items-center gap-1">
+ *   <Kbd>⌘</Kbd>
+ *   <Kbd>K</Kbd>
+ * </span>
+ * ```
+ *
+ * A keycap is display chrome, so it carries no `access` / `visibleWhen`:
+ * like `<Typography>`, it is gated by wrapping it, not by gating itself.
+ */
+export interface KbdProps {
+    /** The key label. Usually one glyph or a short word (`Esc`, `Tab`). */
+    children: ReactNode;
+    /**
+     * Cap size.
+     *
+     * @default 'md'
+     */
+    size?: KbdSize;
+    /**
+     * Utility classes appended to the variant chain. Resolved through
+     * `tailwind-merge`, so a consumer's class always wins over the recipe.
+     *
+     * @default undefined
+     */
+    sx?: string;
+    /**
+     * Escape hatch for the rendered `<kbd>`: `id`, `title`, `data-*`.
+     *
+     * @default undefined
+     */
+    className?: string;
+}
+declare module '@dashforge/tw-tokens' {
+    interface TWComponentDefaults {
+        Kbd?: {
+            defaults?: Partial<KbdVariantProps>;
+        };
+    }
+}
+//# sourceMappingURL=kbd.types.d.ts.map

package/dist/components/Kbd/kbd.variants.d.ts

@@ -0,0 +1,54 @@
+import { type VariantProps } from 'tailwind-variants';
+/**
+ * Tailwind-variants recipe for `<Kbd>`.
+ *
+ * One axis, `size`, because a keycap has no intent: it is chrome around a
+ * literal key, not a status or an action. Colour is fixed to the neutral
+ * ramp, which auto-inverts through the preset's CSS vars, so the cap reads
+ * as a raised surface in light and a recessed one in dark with no `dark:`
+ * variant to keep in sync.
+ *
+ * The border is what makes the cap read as a cap, and it is at `-500`
+ * rather than the `-300` a hairline invites. Measured on `learn/dash`
+ * against both surfaces a keycap realistically sits on:
+ *
+ *   surface neutral-100 ... 1.09 vs page, 1.04 vs card
+ *   surface neutral-200 ... 1.26 / 1.21
+ *   border  neutral-300 ... 1.48 / 1.42
+ *   border  neutral-400 ... 2.52 / 2.42
+ *   border  neutral-500 ... 4.74 / 4.54   <- the first that clears 3:1
+ *
+ * The first draft assumed the `bg-neutral-100` surface would do the
+ * separating and left the border at `-300`. It does not: a neutral surface
+ * one step off the page is ~1.1:1 by construction, and in dark mode it
+ * lands on exactly the same colour as a card, so the cap disappeared into
+ * the panel and only the hairline was left. That is the same shape that
+ * failed on the outline Chip (README-BUG § BUG 40), and it reached the
+ * same tier for the same reason.
+ *
+ * The surface stays as a faint lift, not as the separator.
+ *
+ * `rounded-md` rather than a bare `rounded`, which is hard-coded at
+ * 0.25rem and immune to the radius tokens (README-BUG § BUG 26).
+ */
+export declare const kbdVariants: import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+}, undefined, string[], {
+    size: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+}, undefined, import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+}, undefined, string[], unknown, unknown, undefined>>;
+export type KbdVariants = VariantProps<typeof kbdVariants>;
+//# sourceMappingURL=kbd.variants.d.ts.map

package/dist/{src/components → components}/Select/Select.d.ts

@@ -9,6 +9,6 @@ import type { SelectProps, SelectValue } from './select.types.js';
  *   `<Select<'a' | 'b'> options={…} onChange={…} />`.
  */
 export declare const Select: <V extends SelectValue = string>(props: SelectProps<V> & {
-    ref?: React.Ref<HTMLButtonElement>;
+    ref?: React.Ref<HTMLDivElement>;
 }) => ReactElement | null;
 //# sourceMappingURL=Select.d.ts.map

package/dist/{src/components → components}/Slider/Slider.d.ts

@@ -10,6 +10,6 @@ import type { SliderProps, SliderSingleProps, SliderRangeProps } from './slider.
  *
  * See {@link SliderProps} for the full API surface.
  */
-export declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLSpanElement>>;
+export declare const Slider: import("react").ForwardRefExoticComponent<SliderProps & import("react").RefAttributes<HTMLDivElement>>;
 export type { SliderSingleProps, SliderRangeProps };
 //# sourceMappingURL=Slider.d.ts.map

package/dist/{src/components → components}/Stack/stack.types.d.ts

@@ -1,4 +1,6 @@
 import type { ElementType, HTMLAttributes, ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
 import type { StackGap, StackVariants } from './stack.variants.js';
 /**
  * Subset of `<Stack>` props theme-configurable via
@@ -108,5 +110,45 @@ export interface StackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'classN
      * variant defaults.
      */
     sx?: string;
+    /**
+     * Reactive visibility predicate. When it returns `false` the component
+     * renders `null`. Inside a `<DashForm>` it subscribes reactively to
+     * engine state; outside a form it is evaluated as a plain closure.
+     *
+     * Use it for state-driven hiding. **For permission-driven hiding prefer
+     * `access` with `onUnauthorized: 'hide'`**, which is the semantically
+     * correct path and surfaces properly in RBAC dev tools.
+     *
+     * @default undefined
+     *
+     * @example
+     * ```tsx
+     * <Stack visibleWhen={() => pendingCount > 0}>
+     *   <Typography variant="h3">{pendingCount} pending</Typography>
+     * </Stack>
+     * ```
+     */
+    visibleWhen?: (engine: Engine) => boolean;
+    /**
+     * RBAC requirement, evaluated by the centralized `@dashforge/rbac`
+     * policy engine. Brings Stack to parity with `<Box>`, which has
+     * carried both props since 1.1.0.
+     *
+     * - `onUnauthorized: 'hide'`     → does not render
+     * - `onUnauthorized: 'disable'`  → `aria-disabled` + dimmed; interactive
+     *   children derive their own state from `data-disabled` or carry their
+     *   own `access`
+     * - `onUnauthorized: 'readonly'` → `aria-readonly`, for gated sections
+     *
+     * @default undefined
+     *
+     * @example
+     * ```tsx
+     * <Stack access={{ resource: 'billing', action: 'read', onUnauthorized: 'hide' }}>
+     *   <RevenueCard />
+     * </Stack>
+     * ```
+     */
+    access?: AccessRequirement;
 }
 //# sourceMappingURL=stack.types.d.ts.map

package/dist/{src/components → components}/Stack/stack.variants.d.ts

@@ -182,5 +182,13 @@ export type StackGap = 0 | 0.5 | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16 | 24;
  * `gap` value at render time. Same set as {@link StackGap}. Frozen
  * so callers can't mutate the source of truth.
  */
+/**
+ * The accepted `direction` values, for the dev-time guard in `Stack.tsx`.
+ *
+ * Frozen and exported rather than inlined so the warning cannot drift from
+ * the variant recipe: adding an axis value without adding it here would
+ * make the guard warn about something that works.
+ */
+export declare const STACK_DIRECTION_VALUES: readonly ["row", "col", "row-reverse", "col-reverse"];
 export declare const STACK_GAP_VALUES: readonly StackGap[];
 //# sourceMappingURL=stack.variants.d.ts.map

package/dist/{src/components → components}/TopBar/TopBar.d.ts

@@ -1,4 +1,4 @@
-import type { TopBarProps } from './topBar.types.js';
+import type { TopBarProps, TopBarBrandProps } from './topBar.types.js';
 /**
  * Dashforge TW TopBar — sticky header with 3 named slots.
  *
@@ -30,4 +30,19 @@ import type { TopBarProps } from './topBar.types.js';
  *     appropriate roles (`<nav>`, `<search>`, etc.) where needed.
  */
 export declare function TopBar(props: TopBarProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * `<TopBarBrand>` — the mark-plus-text block for a `<TopBar>`'s `start`
+ * slot.
+ *
+ * ```tsx
+ * <TopBar
+ *   start={<TopBarBrand logo={<Logo />} title="Dashforge" subtitle="src/App.tsx" />}
+ *   end={<UserMenu />}
+ * />
+ * ```
+ *
+ * See {@link TopBarBrandProps} for why it is a sibling export rather than
+ * `TopBar.Brand`, and why it stays layout-only.
+ */
+export declare const TopBarBrand: import("react").ForwardRefExoticComponent<TopBarBrandProps & import("react").RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=TopBar.d.ts.map

package/dist/components/TopBar/topBar.types.d.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from 'react';
+import type { TopBarVariants } from './topBar.variants.js';
+/**
+ * Subset of `<TopBar>` props theme-configurable via
+ * `theme.components.TopBar.defaults` (Option C).
+ */
+export type TopBarVariantProps = Pick<TopBarVariants, 'height' | 'sticky'>;
+declare module '@dashforge/tw-tokens' {
+    interface TWComponentDefaults {
+        TopBar?: {
+            defaults?: Partial<TopBarVariantProps>;
+            slotProps?: TopBarSlotProps;
+        };
+    }
+}
+export interface TopBarSlotProps {
+    root?: {
+        className?: string;
+    };
+    start?: {
+        className?: string;
+    };
+    center?: {
+        className?: string;
+    };
+    end?: {
+        className?: string;
+    };
+}
+/**
+ * Props for `<TopBar>`.
+ *
+ * Pure composition container with 3 named slots — `start`, `center`,
+ * `end` — that fill a sticky horizontal bar.
+ *
+ * Typical patterns:
+ *
+ *   - **start**: mobile menu toggle, brand/logo
+ *   - **center**: Breadcrumbs, page title, global search
+ *   - **end**: notifications icon, user menu, theme toggle
+ *
+ * The component is intentionally minimal: it just lays out the three
+ * regions. All semantics (e.g., `<header role="banner">`) come for
+ * free from rendering as an HTML `<header>` element.
+ */
+export interface TopBarProps {
+    /**
+     * Bar height tier — sm:h-12, md:h-14, lg:h-16.
+     * @default 'md'
+     */
+    height?: TopBarVariants['height'];
+    /**
+     * Apply `position: sticky; top: 0` so the bar stays pinned during
+     * page scroll.
+     * @default true
+     */
+    sticky?: TopBarVariants['sticky'];
+    /** Left-aligned slot (mobile menu, brand). */
+    start?: ReactNode;
+    /** Center slot (breadcrumbs, title). Grows to fill remaining space. */
+    center?: ReactNode;
+    /** Right-aligned slot (actions, user menu). */
+    end?: ReactNode;
+    /** Convenience: render the bar as a plain `<div>` (no banner role). */
+    asDiv?: boolean;
+    /** Root className shortcut. */
+    sx?: string;
+    /** Per-slot className overrides. */
+    slotProps?: TopBarSlotProps;
+    /** Children render between `start` and `end` when no `center` is set. */
+    children?: ReactNode;
+}
+/** Per-slot class overrides for `<TopBarBrand>`. */
+export interface TopBarBrandSlotProps {
+    /** Outer wrapper holding logo, title and subtitle. */
+    root?: {
+        className?: string;
+    };
+    /** The mark. */
+    logo?: {
+        className?: string;
+    };
+    /** Wrapper around the two text lines. */
+    text?: {
+        className?: string;
+    };
+    /** The primary line. */
+    title?: {
+        className?: string;
+    };
+    /** The secondary line. */
+    subtitle?: {
+        className?: string;
+    };
+}
+/**
+ * Props for `<TopBarBrand>` — the "mark plus a line or two of text" block
+ * that fills a `<TopBar>`'s `start` slot. kensaadi/dashforge#63 gap G.
+ *
+ * A **sibling export, not `TopBar.Brand`**, despite how the request was
+ * written: this catalog attaches subcomponents as named siblings
+ * (`Card` / `CardContent` / `CardActionArea`), and one component doing it
+ * differently is worse than matching the request's punctuation.
+ *
+ * It is deliberately layout only: no link, no routing, no click. A brand
+ * that navigates home is a `<Link>` or a router component wrapped around
+ * this, which keeps the router out of the library.
+ *
+ * ⚠️ This lands ahead of kensaadi/dashforge#132, whose job is to freeze the
+ * AppShell and TopBar surface, and #134 lists this helper as one of its
+ * deliverables. It is kept to the smallest shape that removes the
+ * duplication so the audit can adopt or reshape it cheaply.
+ */
+export interface TopBarBrandProps {
+    /** The mark: an svg, an `<img>`, an icon. Omit for text-only brands. */
+    logo?: ReactNode;
+    /**
+     * The primary line, e.g. the product name.
+     */
+    title: ReactNode;
+    /**
+     * The secondary line, e.g. the open file or the current page. Omitted,
+     * the block is a single line and the title centres against the logo.
+     *
+     * @default undefined
+     */
+    subtitle?: ReactNode;
+    /**
+     * Utility classes appended to the root's variant chain, resolved through
+     * `tailwind-merge`.
+     *
+     * @default undefined
+     */
+    sx?: string;
+    /**
+     * Per-slot class overrides.
+     *
+     * @default undefined
+     */
+    slotProps?: TopBarBrandSlotProps;
+}
+//# sourceMappingURL=topBar.types.d.ts.map

package/dist/components/TopBar/topBar.variants.d.ts

@@ -0,0 +1,136 @@
+import { type VariantProps } from 'tailwind-variants';
+/**
+ * Tailwind-variants recipe for `<TopBar>`.
+ *
+ * Slots:
+ *   - `root`   — outer `<header>` (or `<div>` with `asDiv`)
+ *   - `start`  — left region (shrink-to-content)
+ *   - `center` — middle region (grows to fill)
+ *   - `end`    — right region (shrink-to-content)
+ */
+export declare const topBarVariants: import("tailwind-variants").TVReturnType<{
+    height: {
+        sm: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+    };
+    sticky: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    start: string;
+    center: string;
+    end: string;
+}, undefined, {
+    height: {
+        sm: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+    };
+    sticky: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    start: string;
+    center: string;
+    end: string;
+}, import("tailwind-variants").TVReturnType<{
+    height: {
+        sm: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+    };
+    sticky: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string[];
+    start: string;
+    center: string;
+    end: string;
+}, undefined, unknown, unknown, undefined>>;
+export type TopBarVariants = VariantProps<typeof topBarVariants>;
+/**
+ * Recipe for `<TopBarBrand>`.
+ *
+ * `min-w-0` plus `truncate` on both lines is the load-bearing part: a bar
+ * is a fixed-height row, and a long subtitle (a file path, which is the
+ * case this exists for) would otherwise push the `center` and `end` slots
+ * out of the bar rather than ellipsing.
+ */
+export declare const topBarBrandVariants: import("tailwind-variants").TVReturnType<{
+    [key: string]: {
+        [key: string]: import("tailwind-merge").ClassNameValue | {
+            title?: import("tailwind-merge").ClassNameValue;
+            text?: import("tailwind-merge").ClassNameValue;
+            root?: import("tailwind-merge").ClassNameValue;
+            logo?: import("tailwind-merge").ClassNameValue;
+            subtitle?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: import("tailwind-merge").ClassNameValue | {
+            title?: import("tailwind-merge").ClassNameValue;
+            text?: import("tailwind-merge").ClassNameValue;
+            root?: import("tailwind-merge").ClassNameValue;
+            logo?: import("tailwind-merge").ClassNameValue;
+            subtitle?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {}, {
+    root: string;
+    logo: string;
+    text: string;
+    title: string;
+    subtitle: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: import("tailwind-merge").ClassNameValue | {
+            title?: import("tailwind-merge").ClassNameValue;
+            text?: import("tailwind-merge").ClassNameValue;
+            root?: import("tailwind-merge").ClassNameValue;
+            logo?: import("tailwind-merge").ClassNameValue;
+            subtitle?: import("tailwind-merge").ClassNameValue;
+        };
+    };
+} | {}, {
+    root: string;
+    logo: string;
+    text: string;
+    title: string;
+    subtitle: string;
+}, import("tailwind-variants").TVReturnType<unknown, {
+    root: string;
+    logo: string;
+    text: string;
+    title: string;
+    subtitle: string;
+}, undefined, unknown, unknown, undefined>>;
+//# sourceMappingURL=topBar.variants.d.ts.map

package/dist/components/_shared/resolveValidationState.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import type { DashFormBridge } from '@dashforge/ui-core';
+/**
+ * Resolved validation state for a bridge-managed field.
+ *
+ * Returned by `resolveValidationState`, this is consumed by all form
+ * components that surface error + helper text (TextField, Checkbox,
+ * Switch, …) to derive their final render state.
+ */
+export interface ValidationState {
+    error: boolean;
+    helperText: ReactNode;
+}
+/**
+ * Compute `error` + `helperText` for a bridge-managed field.
+ *
+ * **Renderer-agnostic.** Mirrors the MUI-side
+ * `ui/src/components/TextField/textField.validation.ts`. Promoted to a
+ * `_shared/` directory inside `@dashforge/tw` so all 14 bridge-managed
+ * form components reuse the same precedence without depending on a
+ * specific component folder.
+ *
+ * ⚠️ This file is a COPY, not an import. The two sides have to be kept
+ * in step by hand, and once already were not: BUG 17 (2026-09-15)
+ * inverted the `helperText` precedence on the MUI side only, and this
+ * copy kept the broken order for ten days until BUG 32 caught it. The
+ * verification that missed it was a grep for imports of the MUI file,
+ * which by construction cannot reach a copy. **When you change the
+ * precedence here, change it there too — and vice versa.**
+ *
+ * Precedence rules:
+ *
+ *  1. **`error`: the explicit prop wins.** An author who passes `error`
+ *     is forcing the visual state, so it overrides the auto-gate.
+ *  2. **`helperText`: the validation message wins while it is showing;
+ *     the explicit prop is the fallback for the no-error state.** A
+ *     constant hint ("Unique, uppercase") must not swallow the reason a
+ *     required field was rejected — that leaves the user looking at a
+ *     red field with no explanation. See README-BUG.md § BUG 17 / § BUG 32.
+ *  3. **Auto values are gated by interaction.** The bridge's error is
+ *     surfaced only when the field is `touched` OR the form has been
+ *     submitted at least once (`submitCount > 0`). This prevents the
+ *     "error spam while typing" anti-pattern.
+ *
+ * @param name         field name registered with the bridge
+ * @param bridge       active `DashFormBridge` (guaranteed non-null at
+ *                     call sites by the surrounding `if (bridge)`)
+ * @param explicitError    `error` prop from the consumer
+ * @param explicitHelperText `helperText` prop from the consumer
+ */
+export declare function resolveValidationState(name: string, bridge: DashFormBridge, explicitError: boolean | undefined, explicitHelperText: ReactNode | undefined): ValidationState;
+//# sourceMappingURL=resolveValidationState.d.ts.map