@dezkareid/components 0.0.0 → 1.0.0

package/done/2026-03-03-design-system-components/osddt.tasks.md

@@ -0,0 +1,100 @@
+# Task List: Design System Components
+
+---
+
+## Phase 1 — Package Setup
+
+> All Phase 2–7 tasks depend on Phase 1 being complete.
+
+- [x] [S] Configure `package.json`: add `exports` map for `./react`, `./astro`, `./vue` sub-paths, and add `vue` + `astro` as peer dependencies
+- [x] [S] Create directory skeleton: `src/css/`, `src/shared/js/`, `src/shared/types/`, `src/react/`, `src/astro/`, `src/vue/`
+- [x] [S] Create empty barrel files: `src/react/index.ts`, `src/astro/index.ts`, `src/vue/index.ts`
+- [x] [S] Verify `@dezkareid/design-tokens` is installed and its CSS token file is importable; add as dependency if missing
+- [x] [M] Set up Vitest config targeting `src/react/**/*.test.tsx` with jsdom environment and React Testing Library
+
+**Definition of Done**: `package.json` has correct exports and peer deps; all directories exist; Vitest runs (no tests yet, zero failures).
+
+---
+
+## Phase 2 — Button Component
+
+> Depends on: Phase 1
+
+- [x] [S] Define `ButtonProps` interface in `src/shared/types/button.ts` (`variant`, `size`, `disabled`, `children`)
+- [x] [M] Write `src/css/button.module.css` — structure (`.button`, size modifiers `.button--sm/md/lg`) and skin (variant modifiers `.button--primary/secondary`, state modifier `.button--disabled`) using BEM + OOCSS
+- [x] [M] Implement `src/react/Button/index.tsx` — composes BEM classes, forwards native button props
+- [x] [M] Write `src/react/Button/index.test.tsx` — renders primary/secondary variants, renders sm/md/lg sizes, disabled prevents click, has accessible button role
+- [x] [M] Implement `src/astro/Button/index.astro`
+- [x] [M] Implement `src/vue/Button/index.vue`
+
+**Definition of Done**: Button renders all variants and sizes in all three frameworks; React tests pass; no hardcoded colour or spacing values.
+
+---
+
+## Phase 3 — Tag Component
+
+> Depends on: Phase 1
+
+- [x] [S] Define `TagProps` interface in `src/shared/types/tag.ts` (`variant`, `children`)
+- [x] [M] Write `src/css/tag.module.css` — structure (`.tag`) and skin (variant modifiers `.tag--default/success/danger`) using BEM + OOCSS; add comment proposing `--color-danger` semantic token
+- [x] [M] Implement `src/react/Tag/index.tsx` — renders `<span>`, accepts `children`, composes BEM classes
+- [x] [M] Write `src/react/Tag/index.test.tsx` — renders default/success/danger variants, renders arbitrary children content
+- [x] [M] Implement `src/astro/Tag/index.astro`
+- [x] [M] Implement `src/vue/Tag/index.vue`
+
+**Definition of Done**: Tag renders all variants with correct colours in all three frameworks; accepts arbitrary slot/children; React tests pass.
+
+---
+
+## Phase 4 — Card Component
+
+> Depends on: Phase 1
+
+- [x] [S] Define `CardProps` interface in `src/shared/types/card.ts` (`elevation`, `children`; default elevation `'raised'`)
+- [x] [M] Write `src/css/card.module.css` — structure (`.card`) and skin (base skin on `.card`, elevation modifiers `.card--raised/flat`) using BEM + OOCSS; add comment proposing `--shadow-raised` token
+- [x] [M] Implement `src/react/Card/index.tsx` — renders `<div>`, accepts `children`, composes BEM classes
+- [x] [M] Write `src/react/Card/index.test.tsx` — renders children, applies `card--raised` by default, applies `card--flat` when set
+- [x] [M] Implement `src/astro/Card/index.astro`
+- [x] [M] Implement `src/vue/Card/index.vue`
+
+**Definition of Done**: Card renders children inside a themed surface with correct elevation in all three frameworks; React tests pass.
+
+---
+
+## Phase 5 — ThemeToggle Component
+
+> Depends on: Phase 1
+
+- [x] [S] Define `ThemeToggleProps` interface in `src/shared/types/theme-toggle.ts` (no required props)
+- [x] [M] Implement shared theme utilities in `src/shared/js/theme.ts`: `getInitialTheme()`, `applyTheme()`, `persistTheme()` — all SSR-safe with `typeof window` guards
+- [x] [M] Write `src/css/theme-toggle.module.css` — structure (`.theme-toggle`) and skin + state modifier (`.theme-toggle--dark`) using BEM + OOCSS
+- [x] [M] Implement `src/react/ThemeToggle/index.tsx` — uses `useState` + `useEffect`, calls shared theme utilities
+- [x] [L] Write `src/react/ThemeToggle/index.test.tsx` — initialises from `localStorage`, falls back to `prefers-color-scheme`, toggles on click, persists to `localStorage`
+- [x] [M] Implement `src/astro/ThemeToggle/index.astro` — static markup + inline `<script>` calling shared utilities
+- [x] [M] Implement `src/vue/ThemeToggle/index.vue` — uses `ref` + `onMounted`, calls shared utilities
+
+**Definition of Done**: ThemeToggle reads, applies, and persists theme in all three frameworks; React tests pass; no FOUC in Astro (inline script runs before paint).
+
+---
+
+## Phase 6 — Exports & Package Configuration
+
+> Depends on: Phases 2–5
+
+- [x] [S] Update `src/react/index.ts` to re-export `Button`, `Tag`, `Card`, `ThemeToggle`
+- [x] [S] Update `src/astro/index.ts` to re-export all Astro components
+- [x] [S] Update `src/vue/index.ts` to re-export all Vue components
+- [x] [S] Verify `package.json` `exports` paths resolve correctly (smoke check imports)
+
+**Definition of Done**: All components importable from `@dezkareid/components/react`, `/astro`, and `/vue`; no TypeScript errors.
+
+---
+
+## Phase 7 — Documentation
+
+> Depends on: Phase 6
+
+- [x] [M] Update `README.md`: add `@dezkareid/design-tokens` CSS import requirement, add usage examples for Button, Tag, Card, ThemeToggle in all three framework formats
+- [x] [M] Update `AGENTS.md`: add component API summaries (props, variants, slot/children behaviour) for all four components
+
+**Definition of Done**: README covers install, token CSS import, and usage for all components; AGENTS.md describes all component APIs for AI tooling.

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@dezkareid/components",
-  "version": "0.0.0",
+  "version": "1.0.0",
+  "type": "module",
   "description": "A package to export UI components in formats like React, Astro, Vue, etc.",
+  "exports": {
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./astro": "./src/astro/index.ts",
+    "./vue": "./src/vue/index.ts",
+    "./css": {
+      "import": "./dist/components.min.css",
+      "default": "./dist/components.min.css"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react/index.d.ts"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/dezkareid/dezkareid"
@@ -15,8 +36,57 @@
     "access": "public"
   },
   "keywords": [
-    "setup",
-    "package",
-    "npm"
-  ]
-}
+    "design-system",
+    "components",
+    "react",
+    "astro",
+    "vue"
+  ],
+  "peerDependencies": {
+    "astro": ">=4.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "classnames": "2.5.1",
+    "@dezkareid/design-tokens": "0.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "29.0.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.5.2",
+    "@types/classnames": "^2.3.4",
+    "@types/react": "19.2.9",
+    "@vitejs/plugin-react": "5.1.4",
+    "jsdom": "27.4.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "rollup": "4.56.0",
+    "rollup-plugin-postcss": "4.0.2",
+    "typescript": "5.9.3",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "test": "vitest --run"
+  }
+}

package/rollup.config.mjs

@@ -0,0 +1,32 @@
+import typescript from '@rollup/plugin-typescript';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import postcss from 'rollup-plugin-postcss';
+
+export default {
+  input: 'src/react/index.ts',
+  external: ['react', 'react/jsx-runtime'],
+  plugins: [
+    resolve({ extensions: ['.ts', '.tsx'] }),
+    commonjs(),
+    postcss({
+      autoModules: true,
+      extract: 'components.min.css',
+      minimize: true,
+    }),
+    typescript({
+      tsconfig: './tsconfig.json',
+      declaration: true,
+      declarationDir: 'dist',
+      exclude: ['**/*.test.tsx', '**/*.test.ts', 'setupTests.ts'],
+    }),
+  ],
+  output: {
+    dir: 'dist',
+    format: 'es',
+    preserveModules: true,
+    preserveModulesRoot: 'src',
+    entryFileNames: '[name].js',
+    sourcemap: true,
+  },
+};

package/setupTests.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/src/astro/Button/index.astro

@@ -0,0 +1,35 @@
+---
+import type { ButtonProps } from '../../shared/types/button';
+import styles from '../../css/button.module.css';
+
+type Props = ButtonProps & {
+  href?: string;
+  class?: string;
+  [key: string]: unknown;
+};
+
+const {
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  href,
+  class: className,
+  ...rest
+} = Astro.props;
+
+const Tag = href ? 'a' : 'button';
+
+const classes = [
+  styles.button,
+  styles[`button--${variant}`],
+  styles[`button--${size}`],
+  disabled ? styles['button--disabled'] : '',
+  className ?? '',
+]
+  .filter(Boolean)
+  .join(' ');
+---
+
+<Tag class={classes} href={href} disabled={!href && disabled} {...rest}>
+  <slot />
+</Tag>

package/src/astro/Card/index.astro

@@ -0,0 +1,23 @@
+---
+import type { CardProps } from '../../shared/types/card';
+import styles from '../../css/card.module.css';
+
+type Props = CardProps & {
+  class?: string;
+  [key: string]: unknown;
+};
+
+const { elevation = 'raised', class: className, ...rest } = Astro.props;
+
+const classes = [
+  styles.card,
+  styles[`card--${elevation}`],
+  className ?? '',
+]
+  .filter(Boolean)
+  .join(' ');
+---
+
+<div class={classes} {...rest}>
+  <slot />
+</div>

package/src/astro/Tag/index.astro

@@ -0,0 +1,23 @@
+---
+import type { TagProps } from '../../shared/types/tag';
+import styles from '../../css/tag.module.css';
+
+type Props = TagProps & {
+  class?: string;
+  [key: string]: unknown;
+};
+
+const { variant = 'default', class: className, ...rest } = Astro.props;
+
+const classes = [
+  styles.tag,
+  styles[`tag--${variant}`],
+  className ?? '',
+]
+  .filter(Boolean)
+  .join(' ');
+---
+
+<span class={classes} {...rest}>
+  <slot />
+</span>

package/src/astro/ThemeToggle/index.astro

@@ -0,0 +1,63 @@
+---
+import styles from '../../css/theme-toggle.module.css';
+
+type Props = {
+  class?: string;
+};
+
+const { class: className } = Astro.props;
+
+const classes = [styles['theme-toggle'], className ?? ''].filter(Boolean).join(' ');
+---
+
+<!--
+  The inline script runs before first paint to apply the stored theme,
+  preventing a flash of unstyled/wrong-theme content (FOUC).
+-->
+<script is:inline>
+  (function () {
+    var stored = localStorage.getItem('color-scheme');
+    var theme =
+      stored === 'light' || stored === 'dark'
+        ? stored
+        : window.matchMedia('(prefers-color-scheme: dark)').matches
+          ? 'dark'
+          : 'light';
+    document.documentElement.setAttribute('color-scheme', theme);
+  })();
+</script>
+
+<button
+  type="button"
+  class={classes}
+  data-theme-toggle
+  aria-label="Toggle colour scheme"
+>
+  <span data-theme-label>Light</span>
+</button>
+
+<script>
+  import { getInitialTheme, applyTheme, persistTheme } from '../../shared/js/theme';
+
+  const btn = document.querySelector('[data-theme-toggle]') as HTMLButtonElement | null;
+  const label = document.querySelector('[data-theme-label]') as HTMLElement | null;
+
+  if (btn && label) {
+    let current = getInitialTheme();
+
+    function update(theme: 'light' | 'dark') {
+      label!.textContent = theme === 'dark' ? 'Dark' : 'Light';
+      btn!.setAttribute('aria-pressed', String(theme === 'dark'));
+      btn!.classList.toggle('theme-toggle--dark', theme === 'dark');
+    }
+
+    update(current);
+
+    btn.addEventListener('click', () => {
+      current = current === 'light' ? 'dark' : 'light';
+      applyTheme(current);
+      persistTheme(current);
+      update(current);
+    });
+  }
+</script>

package/src/astro/index.ts

@@ -0,0 +1,4 @@
+export { default as Button } from './Button/index.astro';
+export { default as Tag } from './Tag/index.astro';
+export { default as Card } from './Card/index.astro';
+export { default as ThemeToggle } from './ThemeToggle/index.astro';

package/src/css/button.module.css

@@ -0,0 +1,90 @@
+/* =============================================================================
+   BUTTON — BEM + OOCSS
+   Structure classes: layout, sizing, spacing
+   Skin classes: colour, border, typography
+   ============================================================================= */
+
+/* --- Structure: block --- */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  border: none;
+  border-radius: var(--spacing-4);
+  font-family: var(--font-family-base);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--font-line-height-none);
+  text-decoration: none;
+  white-space: nowrap;
+  transition: opacity 0.15s ease;
+}
+
+/* --- Structure: size modifiers --- */
+.button--sm,
+.button--small {
+  padding: var(--spacing-4) var(--spacing-12);
+  font-size: var(--font-size-200);
+}
+
+.button--md,
+.button--medium {
+  padding: var(--spacing-8) var(--spacing-24);
+  font-size: var(--font-size-300);
+}
+
+.button--lg,
+.button--large {
+  padding: var(--spacing-12) var(--spacing-32);
+  font-size: var(--font-size-400);
+}
+
+/* --- Skin: variant modifiers --- */
+.button--primary {
+  background-color: var(--color-primary);
+  color: var(--color-text-inverse);
+  border: 1px solid transparent;
+}
+
+.button--primary:hover:not(.button--disabled) {
+  opacity: 0.88;
+}
+
+.button--secondary,
+.button--outline {
+  background-color: transparent;
+  color: var(--color-primary);
+  border: 1px solid var(--color-primary);
+}
+
+.button--secondary:hover:not(.button--disabled),
+.button--outline:hover:not(.button--disabled) {
+  background-color: var(--color-background-secondary);
+}
+
+.button--success {
+  background-color: var(--color-success);
+  color: var(--color-text-inverse);
+  border: 1px solid transparent;
+}
+
+.button--success:hover:not(.button--disabled) {
+  opacity: 0.88;
+}
+
+.button--ghost {
+  background-color: transparent;
+  color: var(--color-text-primary);
+  border: 1px solid transparent;
+}
+
+.button--ghost:hover:not(.button--disabled) {
+  background-color: var(--color-background-secondary);
+}
+
+/* --- Skin: state modifier --- */
+.button--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+  pointer-events: none;
+}

package/src/css/card.module.css

@@ -0,0 +1,30 @@
+/* =============================================================================
+   CARD — BEM + OOCSS
+   Structure classes: layout, sizing, spacing
+   Skin classes: colour, shadow
+   ============================================================================= */
+
+/* --- Structure: block --- */
+.card {
+  display: block;
+  width: 100%;
+  border-radius: var(--spacing-8);
+  padding: var(--spacing-24);
+}
+
+/* --- Skin: base --- */
+.card {
+  background-color: var(--color-background-secondary);
+  color: var(--color-text-primary);
+}
+
+/* --- Skin: elevation modifiers --- */
+
+/* TODO: Propose --shadow-raised token to the design-tokens package. */
+.card--raised {
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+}
+
+.card--flat {
+  box-shadow: none;
+}

package/src/css/index.ts

@@ -0,0 +1,4 @@
+import './button.module.css';
+import './card.module.css';
+import './tag.module.css';
+import './theme-toggle.module.css';

package/src/css/tag.module.css

@@ -0,0 +1,33 @@
+/* =============================================================================
+   TAG — BEM + OOCSS
+   Structure classes: layout, sizing, spacing
+   Skin classes: colour, border, typography
+   ============================================================================= */
+
+/* --- Structure: block --- */
+.tag {
+  display: inline-flex;
+  align-items: center;
+  border-radius: var(--spacing-4);
+  padding: var(--spacing-4) var(--spacing-8);
+  font-family: var(--font-family-base);
+  font-size: var(--font-size-100);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--font-line-height-none);
+}
+
+/* --- Skin: variant modifiers --- */
+.tag--default {
+  background-color: var(--color-background-secondary);
+  color: var(--color-text-primary);
+}
+
+.tag--success {
+  background-color: var(--color-success);
+  color: var(--color-text-inverse);
+}
+
+.tag--danger {
+  background-color: var(--color-danger);
+  color: var(--color-text-inverse);
+}

package/src/css/theme-toggle.module.css

@@ -0,0 +1,38 @@
+/* =============================================================================
+   THEME TOGGLE — BEM + OOCSS
+   Structure classes: layout, sizing, spacing
+   Skin classes: colour, state
+   ============================================================================= */
+
+/* --- Structure: block --- */
+.theme-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--spacing-8);
+  cursor: pointer;
+  padding: var(--spacing-8) var(--spacing-12);
+  border: none;
+  border-radius: var(--spacing-4);
+  font-family: var(--font-family-base);
+  font-size: var(--font-size-200);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--font-line-height-none);
+}
+
+/* --- Skin: base --- */
+.theme-toggle {
+  background-color: transparent;
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-background-secondary);
+}
+
+.theme-toggle:hover {
+  background-color: var(--color-background-secondary);
+}
+
+/* --- Skin: state modifier (dark mode active) --- */
+.theme-toggle--dark {
+  color: var(--color-primary);
+  border-color: var(--color-primary);
+}

package/src/declarations.d.ts

@@ -0,0 +1,19 @@
+// CSS Modules
+declare module '*.module.css' {
+  const classes: Record<string, string>;
+  export default classes;
+}
+
+// Astro components
+declare module '*.astro' {
+  import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+  const Component: AstroComponentFactory;
+  export default Component;
+}
+
+// Vue SFCs
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const Component: DefineComponent;
+  export default Component;
+}

package/src/react/Button/index.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import { Button } from './index';
+
+describe('Button', () => {
+  it('renders with default variant and size', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
+  });
+
+  it('renders primary variant', () => {
+    render(<Button variant="primary">Primary</Button>);
+    const btn = screen.getByRole('button');
+    expect(btn.className).toMatch(/button--primary/);
+  });
+
+  it('renders secondary variant', () => {
+    render(<Button variant="secondary">Secondary</Button>);
+    const btn = screen.getByRole('button');
+    expect(btn.className).toMatch(/button--secondary/);
+  });
+
+  it('renders sm size', () => {
+    render(<Button size="sm">Small</Button>);
+    expect(screen.getByRole('button').className).toMatch(/button--sm/);
+  });
+
+  it('renders md size', () => {
+    render(<Button size="md">Medium</Button>);
+    expect(screen.getByRole('button').className).toMatch(/button--md/);
+  });
+
+  it('renders lg size', () => {
+    render(<Button size="lg">Large</Button>);
+    expect(screen.getByRole('button').className).toMatch(/button--lg/);
+  });
+
+  it('is disabled when disabled prop is set', () => {
+    render(<Button disabled>Disabled</Button>);
+    const btn = screen.getByRole('button');
+    expect(btn).toBeDisabled();
+    expect(btn.className).toMatch(/button--disabled/);
+  });
+
+  it('does not fire onClick when disabled', async () => {
+    const onClick = vi.fn();
+    render(<Button disabled onClick={onClick}>Disabled</Button>);
+    await userEvent.click(screen.getByRole('button'));
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('fires onClick when enabled', async () => {
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Click</Button>);
+    await userEvent.click(screen.getByRole('button'));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+});