@dashforge/tw 0.1.0-beta

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * @dashforge/tw
+ *
+ * Tailwind-rendered UI components for the Dashforge ecosystem.
+ *
+ * Architectural contract (plan v2 — 2026-05-15):
+ *  - **Props-driven**: each Tailwind utility that matters for the public
+ *    API becomes a typed prop. `sx` + `slotProps` are escape hatches.
+ *  - **Tokens as source of truth**: components reference colors /
+ *    spacing / radius / fontSize through `@dashforge/tw-tokens` via the
+ *    `dashforgePreset()` from `@dashforge/tw-theme`.
+ *  - **Shared bridge with MUI side**: both ecosystems consume
+ *    `@dashforge/forms` + `@dashforge/ui-core` + `@dashforge/rbac`.
+ *    No styling code is shared.
+ *  - **Variant API**: `tailwind-variants` (TV) with `slots` +
+ *    `compoundVariants`.
+ *
+ * F3 surface (tier-1, this release):
+ *  - `<Button>` (action, RBAC only, `asChild` polymorphism)
+ *  - `<TextField>` (bridge-integrated, 7 slots)
+ *  - `<Checkbox>` (bridge-integrated, Radix Checkbox primitive)
+ *  - `<Switch>` (bridge-integrated, Radix Switch primitive)
+ *
+ * @module @dashforge/tw
+ */
+
+// ───── Components ─────
+export { Button } from './components/Button/Button.js';
+export type { ButtonProps } from './components/Button/button.types.js';
+export { buttonVariants } from './components/Button/button.variants.js';
+
+export { TextField } from './components/TextField/TextField.js';
+export type {
+  TextFieldProps,
+  TextFieldSlotProps,
+} from './components/TextField/textField.types.js';
+export { textFieldVariants } from './components/TextField/textField.variants.js';
+
+export { Checkbox } from './components/Checkbox/Checkbox.js';
+export type {
+  CheckboxProps,
+  CheckboxSlotProps,
+} from './components/Checkbox/checkbox.types.js';
+export { checkboxVariants } from './components/Checkbox/checkbox.variants.js';
+
+export { Switch } from './components/Switch/Switch.js';
+export type {
+  SwitchProps,
+  SwitchSlotProps,
+} from './components/Switch/switch.types.js';
+export { switchVariants } from './components/Switch/switch.variants.js';
+
+// F4 tier-2: bridge-integrated multi-choice + multi-line input
+
+export { RadioGroup } from './components/RadioGroup/RadioGroup.js';
+export type {
+  RadioGroupProps,
+  RadioGroupOption,
+  RadioGroupSlotProps,
+} from './components/RadioGroup/radioGroup.types.js';
+export { radioGroupVariants } from './components/RadioGroup/radioGroup.variants.js';
+
+export { Textarea } from './components/Textarea/Textarea.js';
+export type {
+  TextareaProps,
+  TextareaSlotProps,
+} from './components/Textarea/textarea.types.js';
+export { textareaVariants } from './components/Textarea/textarea.variants.js';
+
+// F4-B tier-2 final: numeric input + segmented OTP
+
+export { NumberField } from './components/NumberField/NumberField.js';
+export type {
+  NumberFieldProps,
+  NumberFieldSlotProps,
+} from './components/NumberField/numberField.types.js';
+export { numberFieldVariants } from './components/NumberField/numberField.variants.js';
+
+export { OTPField } from './components/OTPField/OTPField.js';
+export type {
+  OTPFieldProps,
+  OTPFieldSlotProps,
+  OTPFieldMode,
+} from './components/OTPField/otpField.types.js';
+export { otpFieldVariants } from './components/OTPField/otpField.variants.js';
+
+// F5-A tier-3: AAA-grade single-select combobox via React Aria
+
+export { Autocomplete } from './components/Autocomplete/Autocomplete.js';
+export type {
+  AutocompleteProps,
+  AutocompleteOption,
+  AutocompleteSlotProps,
+  AutocompleteValue,
+} from './components/Autocomplete/autocomplete.types.js';
+export { autocompleteVariants } from './components/Autocomplete/autocomplete.variants.js';
+
+// F5-B tier-3: native HTML5 date / time / datetime picker, bridge-integrated.
+
+export {
+  DateTimePicker,
+  isoToInputValue,
+} from './components/DateTimePicker/DateTimePicker.js';
+export type {
+  DateTimePickerProps,
+  DateTimePickerMode,
+  DateTimePickerSlotProps,
+} from './components/DateTimePicker/dateTimePicker.types.js';
+export { dateTimePickerVariants } from './components/DateTimePicker/dateTimePicker.variants.js';
+
+// F6 layout: router-agnostic navigation primitives.
+
+export { Breadcrumbs } from './components/Breadcrumbs/Breadcrumbs.js';
+export type {
+  BreadcrumbsProps,
+  BreadcrumbItem,
+  BreadcrumbsSlotProps,
+  BreadcrumbLinkComponent,
+} from './components/Breadcrumbs/breadcrumbs.types.js';
+export { breadcrumbsVariants } from './components/Breadcrumbs/breadcrumbs.variants.js';
+
+export { LeftNav } from './components/LeftNav/LeftNav.js';
+export type {
+  LeftNavProps,
+  LeftNavNode,
+  LeftNavItem,
+  LeftNavGroup,
+  LeftNavSlotProps,
+  LeftNavLinkComponent,
+} from './components/LeftNav/leftNav.types.js';
+export { leftNavVariants } from './components/LeftNav/leftNav.variants.js';
+
+export { TopBar } from './components/TopBar/TopBar.js';
+export type {
+  TopBarProps,
+  TopBarSlotProps,
+} from './components/TopBar/topBar.types.js';
+export { topBarVariants } from './components/TopBar/topBar.variants.js';
+
+export { AppShell } from './components/AppShell/AppShell.js';
+export type {
+  AppShellProps,
+  AppShellSlotProps,
+} from './components/AppShell/appShell.types.js';
+export { appShellVariants } from './components/AppShell/appShell.variants.js';
+
+// F7 providers: imperative dialogs + transient notifications.
+
+export {
+  ConfirmDialogProvider,
+  useConfirm,
+} from './components/ConfirmDialog/ConfirmDialog.js';
+export type {
+  ConfirmDialogProviderProps,
+  ConfirmDialogSlotProps,
+  ConfirmFn,
+  ConfirmOptions,
+  ConfirmSeverity,
+} from './components/ConfirmDialog/confirmDialog.types.js';
+export { confirmDialogVariants } from './components/ConfirmDialog/confirmDialog.variants.js';
+
+export {
+  SnackbarProvider,
+  useSnackbar,
+} from './components/Snackbar/Snackbar.js';
+export type {
+  SnackbarProviderProps,
+  SnackbarApi,
+  SnackbarOptions,
+  SnackbarRecord,
+  SnackbarSeverity,
+  SnackbarPosition,
+  SnackbarSlotProps,
+} from './components/Snackbar/snackbar.types.js';
+export { snackbarVariants } from './components/Snackbar/snackbar.variants.js';
+
+// ───── Hooks ─────
+export { useAccessState } from './hooks/useAccessState.js';
+
+// ───── Utilities ─────
+export { cn } from './utils/cn.js';
+
+// Re-export tailwind-variants for consumers building app-level variants
+// against the same canonical version used by the library.
+export { tv } from 'tailwind-variants';
+export type { VariantProps } from 'tailwind-variants';
+
+/**
+ * Package version (synced with `package.json` at publish time).
+ */
+export const VERSION = '0.1.0-beta';

package/src/utils/cn.spec.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { cn } from './cn.js';
+
+describe('cn (clsx wrapper)', () => {
+  it('joins truthy class values', () => {
+    expect(cn('a', 'b')).toBe('a b');
+  });
+
+  it('drops falsy values', () => {
+    expect(cn('a', false, null, undefined, '', 'b')).toBe('a b');
+  });
+
+  it('flattens conditional objects', () => {
+    expect(cn('a', { b: true, c: false }, 'd')).toBe('a b d');
+  });
+});

package/src/utils/cn.ts

@@ -0,0 +1,29 @@
+import clsx, { type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * className composition helper for Dashforge TW components.
+ *
+ * Wraps `clsx` (for boolean / object / array compaction) with
+ * `tailwind-merge` (for last-wins conflict resolution between
+ * conflicting Tailwind utilities). This is the override contract
+ * that powers `sx` and `slotProps`:
+ *
+ * ```tsx
+ * cn(buttonVariants({ variant: 'solid', color: 'primary' }), sx)
+ * // sx="bg-red-500" beats the variant's `bg-primary-500`.
+ * ```
+ *
+ * Without `tailwind-merge`, Tailwind's stylesheet output order decides
+ * who wins, which is unpredictable for consumers and breaks the
+ * documented "override always wins" semantics.
+ *
+ * @example
+ * ```tsx
+ * <button className={cn('px-4 py-2', isPrimary && 'bg-primary-500')}>
+ * cn(['inline-flex', { 'opacity-50': disabled }], extra);
+ * ```
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,55 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  // No `references` block intentional — without it, the TS bundler
+  // resolver picks up the workspace `src/index.ts` of each peer
+  // through the path mapping in `tsconfig.base.json`, which is the
+  // canonical source-of-truth. With references, TS preferred each
+  // dep's `dist/index.d.ts` wrapper (`export * from "./src/index"`)
+  // and the chain ambient-re-export through that wrapper silently
+  // dropped re-exports under `bundler` module resolution. The build
+  // chain still runs the deps' `build` targets before this one via
+  // `dependsOn: ["typecheck", "^build"]` so `nx` order is preserved.
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ],
+  "references": [
+    {
+      "path": "../ui-core/tsconfig.lib.json"
+    },
+    {
+      "path": "../tw-tokens/tsconfig.lib.json"
+    },
+    {
+      "path": "../tw-theme/tsconfig.lib.json"
+    },
+    {
+      "path": "../rbac/tsconfig.lib.json"
+    },
+    {
+      "path": "../forms/tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,25 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig(() => ({
+  root: import.meta.dirname,
+  cacheDir: '../../../node_modules/.vite/libs/dashforge/tw',
+  plugins: [react()],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //  plugins: [],
+  // },
+  test: {
+    name: '@dashforge/tw',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/vitest.config.mts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../../node_modules/.vite/libs/dashforge/tw',
+  plugins: [react()],
+  test: {
+    name: '@dashforge/tw',
+    watch: false,
+    globals: true,
+    // Default 'node'. Specs that mount React opt in via the
+    // `// @vitest-environment jsdom` magic comment at file top.
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));