castlecraftstudios-ui 1.0.0 → 1.0.1

package/README.md

@@ -1,73 +1,346 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
-
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+# castlecraftstudios-ui
+
+Accessible, zero-dependency React component library with built-in dark mode support.
+
+[![npm version](https://img.shields.io/npm/v/castlecraftstudios-ui)](https://www.npmjs.com/package/castlecraftstudios-ui)
+[![license](https://img.shields.io/npm/l/castlecraftstudios-ui)](LICENSE)
+[![React](https://img.shields.io/badge/react-%3E%3D18-blue)](https://react.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org)
+
+## Features
+
+- 16 fully typed components — buttons, forms, overlays, feedback, and more
+- Dark mode out of the box — respects `prefers-color-scheme` or a `data-theme` attribute
+- Zero runtime dependencies — no UI library bloat
+- Accessible by default — ARIA attributes, keyboard navigation, focus management
+- Tree-shakable — ESM + CJS dual build
+
+## Installation
+
+```bash
+npm install castlecraftstudios-ui
+```
+
+Then import the stylesheet once at your app root:
+
+```tsx
+import 'castlecraftstudios-ui/styles'
+```
+
+## Quick Start
+
+```tsx
+import { Button, Input, Modal } from 'castlecraftstudios-ui'
+import 'castlecraftstudios-ui/styles'
+
+export default function App() {
+  return <Button variant="primary">Get started</Button>
+}
+```
+
+## Components
+
+### Button
+
+```tsx
+import { Button } from 'castlecraftstudios-ui'
+
+<Button variant="primary" size="md">Save</Button>
+<Button variant="outline" disabled>Cancel</Button>
+<Button variant="ghost" size="sm">Learn more</Button>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost'` | `'primary'` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` |
+| + all `<button>` HTML attributes | | |
+
+---
+
+### Input / Textarea / Select
+
+All three share the same API surface.
+
+```tsx
+import { Input, Textarea, Select } from 'castlecraftstudios-ui'
+
+<Input label="Email" type="email" placeholder="you@example.com" />
+<Input label="Username" error="Already taken" />
+<Input label="Bio" helperText="Keep it short" />
+
+<Textarea label="Description" rows={6} />
+
+<Select label="Country">
+  <option value="us">United States</option>
+  <option value="uk">United Kingdom</option>
+</Select>
+```
+
+| Prop | Type |
+|------|------|
+| `label` | `string` |
+| `helperText` | `string` |
+| `error` | `string` |
+| `size` | `'sm' \| 'md' \| 'lg'` |
+| + native HTML attributes | |
+
+---
+
+### Toggle / Checkbox / Radio
+
+```tsx
+import { Toggle, Checkbox, Radio } from 'castlecraftstudios-ui'
+
+<Toggle label="Enable notifications" defaultChecked />
+<Checkbox label="I agree to the terms" />
+<Radio label="Option A" name="group" value="a" />
+```
+
+---
+
+### Card
+
+```tsx
+import { Card } from 'castlecraftstudios-ui'
+
+<Card variant="elevated" header="Title" footer={<Button>Action</Button>}>
+  Card content goes here.
+</Card>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `'default' \| 'elevated' \| 'outline' \| 'flat'` | `'default'` |
+| `header` | `ReactNode` | — |
+| `footer` | `ReactNode` | — |
+
+---
+
+### Modal
+
+```tsx
+import { useState } from 'react'
+import { Modal, Button } from 'castlecraftstudios-ui'
+
+function Example() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open modal</Button>
+      <Modal
+        open={open}
+        onClose={() => setOpen(false)}
+        title="Confirm action"
+        size="md"
+        footer={<Button onClick={() => setOpen(false)}>Done</Button>}
+      >
+        Are you sure you want to continue?
+      </Modal>
+    </>
+  )
+}
+```
+
+| Prop | Type |
+|------|------|
+| `open` | `boolean` |
+| `onClose` | `() => void` |
+| `title` | `string` |
+| `size` | `'sm' \| 'md' \| 'lg'` |
+| `footer` | `ReactNode` |
+
+Closes on Escape key press or backdrop click.
+
+---
+
+### Alert
+
+```tsx
+import { Alert } from 'castlecraftstudios-ui'
+
+<Alert variant="success" title="Saved!">Your changes have been saved.</Alert>
+<Alert variant="error" title="Error" onDismiss={() => {}}>Something went wrong.</Alert>
+```
+
+| Prop | Type |
+|------|------|
+| `variant` | `'success' \| 'warning' \| 'error' \| 'info'` |
+| `title` | `string` |
+| `onDismiss` | `() => void` |
+
+---
+
+### Toast
+
+```tsx
+import { useState } from 'react'
+import { Toast, Button } from 'castlecraftstudios-ui'
+
+function Example() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Show toast</Button>
+      <Toast
+        open={open}
+        variant="success"
+        title="Done!"
+        onDismiss={() => setOpen(false)}
+      >
+        Your item was created.
+      </Toast>
+    </>
+  )
+}
+```
+
+Renders in a portal at the bottom-right of the viewport.
+
+---
+
+### Badge
+
+```tsx
+import { Badge } from 'castlecraftstudios-ui'
+
+<Badge variant="success">Active</Badge>
+<Badge variant="warning" dot />
+```
+
+| Prop | Type |
+|------|------|
+| `variant` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` |
+| `dot` | `boolean` |
+
+---
+
+### Spinner
+
+```tsx
+import { Spinner } from 'castlecraftstudios-ui'
+
+<Spinner size="md" />
+```
+
+| Prop | Type |
+|------|------|
+| `size` | `'sm' \| 'md' \| 'lg'` |
+
+---
+
+### Tooltip
+
+```tsx
+import { Tooltip, Button } from 'castlecraftstudios-ui'
+
+<Tooltip content="Save your changes" position="top">
+  <Button>Save</Button>
+</Tooltip>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `content` | `string` | — |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` |
+
+---
+
+### DatePicker
+
+```tsx
+import { useState } from 'react'
+import { DatePicker } from 'castlecraftstudios-ui'
+
+function Example() {
+  const [date, setDate] = useState<Date | null>(null)
+
+  return (
+    <DatePicker
+      label="Appointment date"
+      value={date}
+      onChange={setDate}
+      min={new Date()}
+    />
+  )
+}
+```
+
+| Prop | Type |
+|------|------|
+| `label` | `string` |
+| `value` | `Date \| null` |
+| `onChange` | `(date: Date \| null) => void` |
+| `min` | `Date` |
+| `max` | `Date` |
+| `placeholder` | `string` |
+| `disabled` | `boolean` |
+
+---
+
+### Tabs
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from 'castlecraftstudios-ui'
+
+<Tabs defaultValue="overview">
+  <TabList>
+    <Tab value="overview">Overview</Tab>
+    <Tab value="settings">Settings</Tab>
+    <Tab value="billing" disabled>Billing</Tab>
+  </TabList>
+
+  <TabPanel value="overview">Overview content</TabPanel>
+  <TabPanel value="settings">Settings content</TabPanel>
+  <TabPanel value="billing">Billing content</TabPanel>
+</Tabs>
 ```
+
+Supports controlled mode via `value` + `onChange`. Arrow keys, Home, and End navigate between tabs.
+
+## Dark Mode
+
+The library respects the system `prefers-color-scheme` media query automatically. To override explicitly, set a `data-theme` attribute on the root element:
+
+```tsx
+// Force dark mode
+document.documentElement.setAttribute('data-theme', 'dark')
+
+// Force light mode
+document.documentElement.setAttribute('data-theme', 'light')
+
+// Reset to system preference
+document.documentElement.removeAttribute('data-theme')
+```
+
+All colors are driven by CSS custom properties, making it easy to override individual tokens:
+
+```css
+:root {
+  --accent: #7c3aed;        /* primary brand color */
+  --bg: #ffffff;            /* surface background */
+  --text: #374151;          /* body text */
+  --text-h: #111827;        /* heading text */
+  --border: #e5e7eb;        /* borders and dividers */
+}
+```
+
+## TypeScript
+
+Full TypeScript definitions are included. Each component extends its corresponding HTML element's attribute types, so all native props work as expected:
+
+```tsx
+import type { ComponentProps } from 'react'
+import { Button } from 'castlecraftstudios-ui'
+
+// Works — onClick, aria-label, data-*, etc. are all valid
+<Button onClick={handleClick} aria-label="Submit form" data-testid="submit">
+  Submit
+</Button>
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castlecraftstudios-ui",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Accessible, zero-dependency React component library with dark mode support",
   "keywords": [