@dashforge/tw 0.11.0-beta → 1.0.0

package/dist/components/Grid/grid.variants.d.ts

@@ -0,0 +1,453 @@
+import { type VariantProps } from 'tailwind-variants';
+/**
+ * `gridVariants` — CSS Grid container + item, polymorphic in role.
+ *
+ * Architectural choice (planned with the user — F9 deep dive):
+ *
+ *   Pattern is MUI Grid v2 from the API side (`<Grid container>` +
+ *   `<Grid xs={6}>`), but engine is REAL CSS Grid under the hood
+ *   (`display: grid` + `grid-template-columns: repeat(N, 1fr)` +
+ *   `col-span-*`). MUI v2 uses flexbox + basis percentages — historical
+ *   IE11 reasons. In 2026, CSS Grid is universally supported AND
+ *   Tailwind ships `grid-cols-*` / `col-span-*` natively, so flexbox
+ *   would be a downgrade.
+ *
+ * Two distinct shapes coexist in the same TV recipe:
+ *
+ *   • container=true   — display:grid + cols + gap + autoFlow
+ *   • container=false  — col-span at each breakpoint (xs/sm/md/lg/xl)
+ *
+ *   The discriminated union lives in grid.types.ts (TypeScript-level);
+ *   here the TV catalogue exposes every axis so the consumer's choice
+ *   triggers the right classes regardless of which role the component
+ *   is playing. Unused axes produce no classes (TV silently drops
+ *   undefined variants), so a container Grid never accidentally emits
+ *   `col-span-6` and an item Grid never accidentally emits `grid`.
+ *
+ * Mapping table size:
+ *   • cols                  : 6 entries (12, 6, 4, 3, 2, 1)
+ *   • autoFlow              : 5 entries
+ *   • span axes (5×14)      : 70 entries (xs/sm/md/lg/xl × {1..12, auto, full})
+ *   • gap / gapX / gapY     : 33 entries (11 steps × 3 axes)
+ *
+ *   Total: ~115 literal class names. All explicit, all Tailwind-scannable.
+ *   Bundle CSS impact when fully exercised: ~3 KB gz (mostly the
+ *   responsive col-span set).
+ */
+export declare const gridVariants: import("tailwind-variants").TVReturnType<{
+    container: {
+        true: string;
+    };
+    cols: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        12: string;
+    };
+    autoFlow: {
+        row: string;
+        col: string;
+        dense: string;
+        'row-dense': string;
+        'col-dense': string;
+    };
+    spacing: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingX: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingY: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    xs: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    sm: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    md: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    lg: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    xl: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+}, undefined, "", {
+    container: {
+        true: string;
+    };
+    cols: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        12: string;
+    };
+    autoFlow: {
+        row: string;
+        col: string;
+        dense: string;
+        'row-dense': string;
+        'col-dense': string;
+    };
+    spacing: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingX: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingY: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    xs: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    sm: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    md: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    lg: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    xl: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+}, undefined, import("tailwind-variants").TVReturnType<{
+    container: {
+        true: string;
+    };
+    cols: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        12: string;
+    };
+    autoFlow: {
+        row: string;
+        col: string;
+        dense: string;
+        'row-dense': string;
+        'col-dense': string;
+    };
+    spacing: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingX: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    spacingY: {
+        0: string;
+        '0.5': string;
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        6: string;
+        8: string;
+        12: string;
+        16: string;
+        24: string;
+    };
+    xs: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    sm: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    md: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    lg: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+    xl: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+        6: string;
+        7: string;
+        8: string;
+        9: string;
+        10: string;
+        11: string;
+        12: string;
+        auto: string;
+        full: string;
+    };
+}, undefined, "", unknown, unknown, undefined>>;
+export type GridVariants = VariantProps<typeof gridVariants>;
+//# sourceMappingURL=grid.variants.d.ts.map

package/dist/components/Grid/grid.variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid.variants.d.ts","sourceRoot":"","sources":["../../../src/components/Grid/grid.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CA6FvB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/components/LeftNav/LeftNav.d.ts

@@ -0,0 +1,34 @@
+import type { LeftNavProps } from './leftNav.types.js';
+/**
+ * Dashforge TW LeftNav — router-agnostic sidebar navigation.
+ *
+ * Pure presentational. The consumer wires `activeId` from the current
+ * route. Each row renders as a real `<a>` (with `href`) or a `<button>`
+ * (with `onSelect`); `linkComponent` swaps in a router-aware link
+ * component for SPA navigation.
+ *
+ * Modes:
+ *   - **Expanded** (`collapsed={false}`): full-width with labels +
+ *     badges + group children visible.
+ *   - **Rail** (`collapsed={true}`): 56px wide, icons only, labels
+ *     hidden from sighted users (still announced to screen readers via
+ *     `sr-only`). Group children are hidden — clicking the group
+ *     header is a no-op visually in rail mode (consumer is expected
+ *     to either expand the nav or surface a flyout in a follow-up).
+ *
+ * **A11y**:
+ *   - `<nav aria-label="…">` landmark.
+ *   - `aria-current="page"` on the active row.
+ *   - Groups expose `aria-expanded` / `aria-controls` and the children
+ *     wrapper is `role="region" aria-labelledby="…-header"`.
+ *   - Rail-mode tooltips via the native `title` attribute (preserves
+ *     hover discoverability when labels are visually hidden).
+ *
+ * **Re-render contract**:
+ *   - Rows are extracted into stable sub-components so a single
+ *     `activeId` change re-renders all rows but each does only its
+ *     own `useAccessState` lookup; this is the price of per-row RBAC.
+ *   - Group expand/collapse re-renders ONLY that group (local state).
+ */
+export declare function LeftNav(props: LeftNavProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=LeftNav.d.ts.map

package/dist/components/LeftNav/LeftNav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeftNav.d.ts","sourceRoot":"","sources":["../../../src/components/LeftNav/LeftNav.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIV,YAAY,EACb,MAAM,oBAAoB,CAAC;AA+M5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,2CAkF1C"}

package/dist/components/LeftNav/leftNav.types.d.ts

@@ -0,0 +1,136 @@
+import type { ReactNode, ComponentType, AnchorHTMLAttributes, Ref } from 'react';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { LeftNavVariants } from './leftNav.variants.js';
+/**
+ * One row in the LeftNav. May be either a clickable item OR a group
+ * (a header that owns nested children, optionally collapsible).
+ */
+export type LeftNavNode = LeftNavItem | LeftNavGroup;
+export interface LeftNavItem {
+    kind?: 'item';
+    /** Stable id used for `activeId` matching + React keys. */
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    /**
+     * Destination for navigation. Omit for a pure-callback item (use
+     * `onSelect`).
+     */
+    href?: string;
+    /** Fired when the row is clicked (in addition to navigation). */
+    onSelect?: () => void;
+    /** Optional pill / counter rendered to the right of the label. */
+    badge?: ReactNode;
+    /** Per-item disabled flag. */
+    disabled?: boolean;
+    /** RBAC access requirement — hides / disables the row. */
+    access?: AccessRequirement;
+}
+export interface LeftNavGroup {
+    kind: 'group';
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    children: LeftNavItem[];
+    /**
+     * Initial expanded state when used in uncontrolled mode. Default
+     * `true` (groups open by default — most app navs want immediate
+     * visibility).
+     */
+    defaultExpanded?: boolean;
+    /** Controlled expanded state. Provide `onExpandedChange` to update. */
+    expanded?: boolean;
+    /** RBAC access requirement — hides / disables the whole group. */
+    access?: AccessRequirement;
+}
+/**
+ * Polymorphic link component prop. Defaults to `<a>`. Pass a
+ * router-aware component (react-router `Link`, Next `Link`) for SPA
+ * navigation.
+ */
+export type LeftNavLinkComponent = ComponentType<AnchorHTMLAttributes<HTMLAnchorElement> & {
+    ref?: Ref<HTMLAnchorElement>;
+}>;
+export interface LeftNavSlotProps {
+    root?: {
+        className?: string;
+    };
+    brand?: {
+        className?: string;
+    };
+    list?: {
+        className?: string;
+    };
+    item?: {
+        className?: string;
+    };
+    itemLink?: {
+        className?: string;
+    };
+    itemActive?: {
+        className?: string;
+    };
+    itemIcon?: {
+        className?: string;
+    };
+    itemLabel?: {
+        className?: string;
+    };
+    itemBadge?: {
+        className?: string;
+    };
+    group?: {
+        className?: string;
+    };
+    groupHeader?: {
+        className?: string;
+    };
+    groupChildren?: {
+        className?: string;
+    };
+    footer?: {
+        className?: string;
+    };
+    collapseToggle?: {
+        className?: string;
+    };
+}
+/**
+ * Props for `<LeftNav>`.
+ *
+ * Router-agnostic sidebar navigation. The consumer drives the active
+ * item via `activeId` (typically derived from the current route).
+ *
+ * Rail / drawer responsive behaviour is handled by `<AppShell>`; this
+ * component renders the actual nav content and exposes a `collapsed`
+ * prop for the icon-only "rail" rendering.
+ */
+export interface LeftNavProps extends LeftNavVariants {
+    items: LeftNavNode[];
+    /** Currently-active item id (highlight + `aria-current="page"`). */
+    activeId?: string;
+    /**
+     * Icon-only rail mode. When `true`, labels and group children are
+     * visually hidden (kept for screen readers via `sr-only`).
+     */
+    collapsed?: boolean;
+    /** Fired when the user clicks the collapse-toggle button. */
+    onCollapseChange?: (collapsed: boolean) => void;
+    /** Fired when a group's expanded state changes (controlled or not). */
+    onGroupExpandedChange?: (groupId: string, expanded: boolean) => void;
+    /** Brand / logo node rendered at the top. */
+    brand?: ReactNode;
+    /** Footer node (e.g., user badge). */
+    footer?: ReactNode;
+    /** Override the link component. @default 'a' */
+    linkComponent?: LeftNavLinkComponent;
+    /** Visible label of the nav landmark. @default 'Main navigation' */
+    ariaLabel?: string;
+    /** Root className shortcut. */
+    sx?: string;
+    /** Per-slot className overrides. */
+    slotProps?: LeftNavSlotProps;
+    /** Show / hide the collapse toggle button. @default true */
+    showCollapseToggle?: boolean;
+}
+//# sourceMappingURL=leftNav.types.d.ts.map

package/dist/components/LeftNav/leftNav.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leftNav.types.d.ts","sourceRoot":"","sources":["../../../src/components/LeftNav/leftNav.types.ts"],"names":[],"mappings":"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"}