@hirobius/design-system 0.8.1

package/dist/types/src/app/components/text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Text — polymorphic typography primitive spanning the full HDS type ramp.
+ *
+ * @category Typography
+ * @tier primitive
+ * @doc-exempt: typography primitive is documented through the Typography ramp page (TypographyPage), not as a standalone component card
+ */
+import { type CSSProperties, type ElementType, type HTMLAttributes, type ReactNode } from 'react';
+type TextVariant = 'display' | 'heading1' | 'heading2' | 'heading3' | 'body' | 'ui' | 'eyebrow' | 'caption' | 'technical' | 'badge' | 'docLede' | 'docBody' | 'docSmall' | 'docCode';
+type TextTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div';
+/** @public */
+export type TextProps = {
+    children: ReactNode;
+    variant: TextVariant;
+    as?: TextTag | ElementType;
+    className?: string;
+    style?: CSSProperties;
+} & HTMLAttributes<HTMLElement>;
+export declare const Text: import("react").ForwardRefExoticComponent<{
+    children: ReactNode;
+    variant: TextVariant;
+    as?: TextTag | ElementType;
+    className?: string;
+    style?: CSSProperties;
+} & HTMLAttributes<HTMLElement> & import("react").RefAttributes<HTMLElement>>;
+export {};

package/dist/types/src/app/components/tile-grid.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @category Layout
+ * @tier primitive
+ */
+import * as React from 'react';
+/** @public */
+export interface TileGridProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Minimum tile width before the grid wraps. Defaults to 260px. */
+    minTileWidth?: string;
+    /** Gap token between tiles. Defaults to 'sm' (12px). */
+    gap?: 'xs' | 'sm' | 'md';
+}
+/**
+ * Auto-fill responsive grid for status/micro tiles. Wraps tile children in a
+ * one-line grid declaration so pages don't repeat the auto-fill minmax recipe.
+ */
+export declare const TileGrid: React.ForwardRefExoticComponent<TileGridProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/components/toast.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Toast — transient feedback notifications (Radix Toast).
+ * @category Feedback
+ * @tier pattern
+ * @doc-exempt: no Overlays/Feedback-overlay doc page yet — add demo when created
+ *
+ * Imperative API: wrap the app once in <ToastProvider>, then call
+ * `useToast().toast({ title, description, tone })` from anywhere. Radix Toast
+ * (@radix-ui/react-toast) owns the a11y live-region, auto-dismiss timing,
+ * swipe-to-dismiss, and viewport portal.
+ *
+ *   function App() {
+ *     return <ToastProvider><Page /></ToastProvider>;
+ *   }
+ *   function SaveButton() {
+ *     const { toast } = useToast();
+ *     return <Button onClick={() => toast({ title: 'Saved', tone: 'success' })}>Save</Button>;
+ *   }
+ */
+import * as React from 'react';
+import * as ToastPrimitive from '@radix-ui/react-toast';
+/** @public */
+export type ToastTone = 'neutral' | 'info' | 'success' | 'danger' | 'warning';
+/** @public */
+export interface ToastOptions {
+    /** Headline line — the primary message. */
+    title: string;
+    /** Optional supporting line below the title. */
+    description?: string;
+    /** Semantic tone — tints the leading icon. */
+    tone?: ToastTone;
+    /** Auto-dismiss in ms. Falls back to the provider default. */
+    duration?: number;
+}
+interface ToastContextValue {
+    /** Enqueue a toast; returns its id. */
+    toast: (options: ToastOptions) => string;
+    /** Dismiss a toast by id. */
+    dismiss: (id: string) => void;
+}
+/** Access the imperative toast API. Must be called under <ToastProvider>. */
+export declare function useToast(): ToastContextValue;
+/** @public */
+export interface ToastProviderProps {
+    children?: React.ReactNode;
+    /** Default auto-dismiss in ms (Radix default is 5000). */
+    duration?: number;
+    /** Swipe-to-dismiss direction. */
+    swipeDirection?: React.ComponentProps<typeof ToastPrimitive.Provider>['swipeDirection'];
+}
+/**
+ * Provider + viewport for the toast system. Wrap the app root once.
+ * @public
+ */
+export declare function ToastProvider({ children, duration, swipeDirection, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/app/components/toggle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HdsToggle — boolean on/off toggle with animated thumb.
+ * @category Inputs
+ * @tier primitive
+ */
+import type { InputHTMLAttributes } from 'react';
+/** HdsToggle — boolean on/off toggle with animated thumb. */
+export type HdsToggleDemoState = 'rest' | 'hover' | 'focused' | 'pressed' | 'disabled';
+interface ToggleProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'checked' | 'onChange'> {
+    /** Toggle label displayed next to the control. */
+    label: string;
+    /** Current checked state. */
+    checked: boolean;
+    /** Called when the toggle changes. */
+    onChange: (v: boolean) => void;
+}
+export declare const HdsToggle: import("react").ForwardRefExoticComponent<ToggleProps & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist/types/src/app/components/token.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Token - reflective token specimen for unified node-based token views.
+ * @category Display
+ * @tier primitive
+ */
+import React from 'react';
+type TokenBaseProps = {
+    className?: string;
+    fullWidth?: boolean;
+    nowrap?: boolean;
+    isSourceNode?: boolean;
+    pathDisplayMode?: 'full' | 'compressed';
+    pathDisplayDepth?: number;
+    pathDisplayLeadingDot?: boolean;
+    nodeRef?: (el: HTMLElement | null) => void;
+    'aria-label'?: string;
+    /** When true, overflow ellipsis appears at the start (left) instead of the end. */
+    truncateFromStart?: boolean;
+};
+type TokenNodeSurfaceProps = TokenBaseProps & {
+    variant?: 'node';
+    children: React.ReactNode;
+    /** Optional explicit token path for deep-linking node instances. Falls back to children when omitted. */
+    tokenPath?: string;
+    isSelected?: boolean;
+    onClick?: () => void;
+    swatchVar?: string;
+    /** Optional left-side slot for compact node content, e.g. curve previews. */
+    leadingSlot?: React.ReactNode;
+};
+/**
+ * @deprecated `variant="diagram"` is a compatibility alias that resolves to the
+ * canonical `variant="node"` treatment; its diagram-only props (value,
+ * accentColor, description, rawValue) are no longer rendered. Migrate to
+ * `variant="node"`.
+ * @removeIn 1.0.0
+ */
+type TokenDiagramProps = TokenBaseProps & {
+    variant: 'diagram';
+    label: string;
+    value: string;
+    accentColor: string;
+    swatchVar?: string;
+    description?: React.ReactNode;
+    rawValue?: React.ReactNode;
+    onClick?: () => void;
+};
+type TokenProps = TokenNodeSurfaceProps | TokenDiagramProps;
+/**
+ * Token - unified token component.
+ *
+ * variant="node" renders the canonical token surface.
+ * variant="diagram" is a DEPRECATED compatibility alias (see TokenDiagramProps;
+ * @removeIn 1.0.0) that now resolves to the same node treatment.
+ * Node content can use a left-side slot for swatches or other compact previews.
+ */
+/** @public */
+export declare function Token(props: TokenProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/app/components/tooltip.d.ts

@@ -0,0 +1,33 @@
+/** @internal — utility-tier component; not part of @hirobius/design-system public API. */
+/**
+ * @tier utility
+ */
+/**
+ * Tooltip — HDS image interaction tooltip
+ *
+ * A pill-shaped label (brand blue / white text) that indicates an image
+ * is expandable. Supports two render modes:
+ *
+ *   'cursor'   — fixed-positioned portal tracking the mouse cursor.
+ *                Appears offset from the cursor tip on hover.
+ *   'centered' — absolute overlay centered within the nearest positioned
+ *                ancestor. Used for keyboard-focus state so keyboard
+ *                users get an identical visual treatment.
+ *
+ * Rendered by AssetImg whenever `expandable` is true and an `onClick`
+ * handler is provided — no per-call configuration needed at the call site.
+ */
+interface TooltipProps {
+    /** Controls visibility and drives AnimatePresence enter/exit. */
+    visible: boolean;
+    /** Render strategy for cursor-following or centered placement. */
+    mode: 'cursor' | 'centered';
+    /** Pill label text. */
+    label?: string;
+    /** Cursor X position in client coordinates. */
+    x?: number;
+    /** Cursor Y position in client coordinates. */
+    y?: number;
+}
+export declare function Tooltip({ visible, mode, label, x, y }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/app/context/DemoStateContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DemoStateContext — React context for freezing HDS component demos into a fixed visual state.
+ *
+ * Replaces the forceHover/forceFocus/forcePressed prop trio on Button and NavItem.
+ * Wrap any demo with <FreezeState state="hover"> and every HDS component inside will
+ * render that visual state without wiring individual force props.
+ *
+ * Components read via useFrozenState():
+ *   frozenState ?? demoState prop → effectiveDemoState
+ *
+ * This means the matrix cells can still pass demoState as a prop and it will work,
+ * while FreezeState wrapping provides a cleaner compositional override.
+ */
+import { type ReactNode } from 'react';
+/** Freeze all HDS demo components inside to the given visual state. */
+export declare function FreezeState({ state, children }: {
+    state: string;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Read the nearest frozen demo state, or null if not inside a FreezeState. */
+export declare function useFrozenState(): string | null;

package/dist/types/src/app/context/FontContext.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export declare function FontProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/src/app/context/LanguageContext.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+type AppLanguage = 'en';
+type AppDirection = 'ltr' | 'rtl';
+interface LanguageOption {
+    language: AppLanguage;
+    dir: AppDirection;
+    label: string;
+    nativeLabel: string;
+}
+interface LanguageContextValue {
+    language: AppLanguage;
+    direction: AppDirection;
+    isRtl: boolean;
+    setLanguage: (language: AppLanguage) => void;
+    setDirection: (direction: AppDirection) => void;
+    toggleDirection: () => void;
+    options: Record<AppLanguage, LanguageOption>;
+}
+export declare function LanguageProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useLanguage(): LanguageContextValue;
+export {};

package/dist/types/src/app/context/RouterContext.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RouterContext — router-adapter seam for @hirobius/design-system.
+ *
+ * HDS components never import a router. Navigation is sourced from an injected
+ * adapter so the library works in three modes:
+ *
+ *   1. Zero-router (default)  — no provider; links are plain <a> and navigate
+ *      falls back to window.location. Drop-in for apps with no router
+ *      (e.g. job-hunt, a plain Vite/React app).
+ *   2. react-router consumers — wrap the app once in <HdsRouterProvider> with an
+ *      adapter that bridges useNavigate()/useLocation()/<Link>. The docs site
+ *      does this internally via ReactRouterBridge (NOT exported).
+ *   3. Next.js / other routers — same seam: provide an adapter mapping to that
+ *      router's navigation + Link.
+ *
+ * IMPORTANT: this module MUST NOT import react-router (or any router). It is the
+ * router-free contract every consumer can satisfy.
+ *
+ * @doc-ignore — provider/hook seam (like ThemeProvider et al.), not a visual
+ *   component; it carries no Figma specimen or docs page, so manifest discovery
+ *   must skip it despite the Hds* name prefix.
+ */
+import { type AnchorHTMLAttributes, type ReactNode } from 'react';
+/** Options forwarded to a router's navigate call (state preserved for SPA nav). */
+export interface HdsNavigateOptions {
+    /** Replace the current history entry instead of pushing a new one. */
+    replace?: boolean;
+    /** Opaque router state (e.g. scroll restoration hints). Ignored by the anchor default. */
+    state?: unknown;
+}
+/** Props for the injectable link component. Mirrors react-router's `<Link to>`. */
+export interface HdsLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    /** Destination route or URL. */
+    to: string;
+    children?: ReactNode;
+}
+/** A link component the host app supplies (or the anchor default below). */
+export type HdsLinkComponent = React.ComponentType<HdsLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+/** The navigation surface HDS components consume. */
+export interface HdsRouterAdapter {
+    /** Navigate to an href. The anchor default uses window.location.assign. */
+    navigate: (href: string, options?: HdsNavigateOptions) => void;
+    /** Current path (e.g. "/color"). Used for active-route detection. */
+    currentPath: string;
+    /** Link component for client-side nav. Defaults to a plain anchor. */
+    LinkComponent: HdsLinkComponent;
+}
+export interface HdsRouterProviderProps {
+    adapter: HdsRouterAdapter;
+    children?: ReactNode;
+}
+/**
+ * Provide a router adapter to all HDS components below. Wrap your app root once.
+ */
+export declare function HdsRouterProvider({ adapter, children }: HdsRouterProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the active router adapter. With no provider, returns a router-free
+ * fallback: navigate → window.location.assign (SSR-guarded), currentPath read
+ * fresh from window.location, LinkComponent → the anchor default.
+ */
+export declare function useHdsRouter(): HdsRouterAdapter;

package/dist/types/src/app/context/TenantContext.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+export type TenantSlug = 'hirobius' | 'concrete-creations' | (string & {});
+interface TenantCtx {
+    /** Active tenant slug, or null in single-tenant mode. */
+    tenantSlug: TenantSlug | null;
+}
+/**
+ * TenantProvider
+ *
+ * Reads VITE_TENANT_SLUG from the Vite environment and, if set, writes
+ * `data-tenant="<slug>"` onto `<html>` so CSS tenant-scope selectors
+ * (e.g. `[data-tenant="acme"] .hds-button`) resolve correctly at runtime.
+ *
+ * Single-tenant deployments that never set VITE_TENANT_SLUG are unaffected:
+ * no attribute is written and no context value is populated.
+ */
+export declare function TenantProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Returns the active tenant slug (null in single-tenant mode). */
+export declare function useTenant(): TenantCtx;
+/**
+ * useTenantOnDocument
+ *
+ * Imperatively applies `data-tenant` to `<html>` — useful when the
+ * provider wraps only part of the tree but you need document-wide scope.
+ */
+export declare function useTenantOnDocument(slug: TenantSlug): void;
+export {};

package/dist/types/src/app/context/ThemeContext.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+type Density = 'comfortable' | 'compact';
+/** Three-way mode: follow OS, force light, or force dark. */
+export type ThemeMode = 'system' | 'light' | 'dark';
+interface ThemeCtx {
+    isDark: boolean;
+    toggleDark: () => void;
+    mode: ThemeMode;
+    setMode: (m: ThemeMode) => void;
+    density: Density;
+    toggleDensity: () => void;
+    setDensity: (d: Density) => void;
+}
+export declare function ThemeProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useTheme(): ThemeCtx;
+export {};

package/dist/types/src/app/context/TokenDisplayContext.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+interface TokenDisplayContextType {
+    showCss: boolean;
+    setShowCss: (val: boolean) => void;
+    toggleCss: () => void;
+}
+export declare function TokenDisplayProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useTokenDisplay(): TokenDisplayContextType;
+export {};

package/dist/types/src/app/context/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @hirobius/design-system/contexts
+ *
+ * App-shell providers + hooks shared by the design-system site and any
+ * consuming app (e.g. the ops dashboard). These wrap the document with the
+ * theme/density, reading-direction, tenant, and font state the tokens and
+ * components rely on. Wrap your app root in:
+ *
+ *   <TenantProvider><LanguageProvider><ThemeProvider><FontProvider>
+ *     {app}
+ *   </FontProvider></ThemeProvider></LanguageProvider></TenantProvider>
+ */
+export * from './ThemeContext';
+export * from './LanguageContext';
+export * from './TenantContext';
+export * from './FontContext';
+export * from './DemoStateContext';
+export * from './TokenDisplayContext';
+export * from './RouterContext';

package/dist/types/src/app/data/manifest-types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * manifest-types.ts — canonical TypeScript types for the HDS manifest contracts.
+ *
+ * Single source of truth for:
+ *   - SystemManifest / ManifestComponentSpec (virtual:hds-manifest)
+ *   - ComponentApiManifest / ManifestApiComponent (component-api.json)
+ *   - Supporting building-block types
+ *
+ * All fields are OPTIONAL (broad superset) — the generated manifest JSON is
+ * the runtime source of truth; consumers that need a field to be required
+ * should derive a local narrowed type via intersection, e.g.:
+ *
+ *   type DocSpec = ManifestComponentSpec & { category: string; figmaUrl: string | null };
+ *
+ * IMPORTANT: `props` means two different things across the two manifests:
+ *   - ManifestComponentSpec.props  → Record<string, ManifestPropSpec>   (shape metadata)
+ *   - ManifestApiComponent.props   → ManifestApiPropRow[]               (documentation rows)
+ * Keep them as DISTINCT types — do not merge.
+ */
+/** Shape metadata for a single prop as stored in componentSpecs[name].props. */
+export type ManifestPropSpec = {
+    type?: string;
+    values?: Array<string | number | boolean>;
+    default?: string | number | boolean;
+    optional?: boolean;
+};
+/** A named slot declared on a component spec. */
+export type ManifestSlot = {
+    name?: string;
+    figmaSlotName?: string;
+    tokenBinding?: Record<string, string>;
+};
+/**
+ * A documentation row for a single prop as stored in
+ * ComponentApiManifest.components[name].props (array, not Record).
+ */
+export type ManifestApiPropRow = {
+    name: string;
+    type?: string;
+    default?: string;
+    required?: boolean;
+    description?: string;
+};
+/** A role token entry from manifest.tokens.role. */
+export type RoleToken = {
+    path?: string;
+    cssVar?: string;
+    description?: string;
+    alias?: string;
+};
+/**
+ * A single entry in SystemManifest.componentSpecs (or .utilities).
+ * Superset of every field any consumer declares — all fields are optional.
+ */
+export type ManifestComponentSpec = {
+    category?: string;
+    description?: string;
+    figmaUrl?: string | null;
+    figmaId?: string | null;
+    figmaLink?: string | null;
+    filePath?: string;
+    hidden?: boolean;
+    docExempt?: boolean;
+    tier?: string;
+    stability?: 'stable' | 'beta';
+    consumers?: string[];
+    tokenMapping?: Record<string, string>;
+    preview?: {
+        exportName?: string;
+        sizing?: 'compact' | 'panel' | 'full';
+    };
+    /** Shape metadata keyed by prop name. Distinct from API manifest prop rows. */
+    props?: Record<string, ManifestPropSpec>;
+    propConstraints?: Record<string, ManifestPropSpec | Record<string, unknown>>;
+    requiredProps?: string[];
+    slots?: ManifestSlot[];
+};
+/**
+ * Alias of ManifestComponentSpec for hds-search.ts back-compat.
+ * @deprecated Use ManifestComponentSpec directly in new code.
+ */
+export type ManifestSpec = ManifestComponentSpec;
+/** The root SystemManifest shape (virtual:hds-manifest). */
+export type SystemManifest = {
+    name?: string;
+    version?: string;
+    systemSpecs?: {
+        engine?: string;
+        icons?: string;
+        tokens?: string;
+        styling?: string;
+        [key: string]: string | undefined;
+    };
+    componentInventory?: string[];
+    componentSpecs?: Record<string, ManifestComponentSpec>;
+    utilities?: Record<string, ManifestComponentSpec>;
+    tokens?: {
+        role?: Record<string, RoleToken> | RoleToken[];
+        [key: string]: unknown;
+    };
+};
+/**
+ * A single entry in ComponentApiManifest.components.
+ * Uses ManifestApiPropRow[] (array) — distinct from ManifestComponentSpec.props (Record).
+ */
+export type ManifestApiComponent = {
+    filePath?: string;
+    category?: string;
+    hidden?: boolean;
+    figmaUrl?: string | null;
+    description?: string;
+    /** Documentation prop rows — array, not a Record. */
+    props?: ManifestApiPropRow[];
+    guides?: Array<{
+        label: string;
+        text: string;
+    }>;
+    observedTokens?: Array<{
+        raw: string;
+        tokenPath?: string;
+    }>;
+};
+/** The root ComponentApiManifest shape (component-api.json). */
+export type ComponentApiManifest = {
+    generatedAt?: string;
+    source?: string;
+    components?: Record<string, ManifestApiComponent>;
+};