@stamcat/craftsman 0.0.31-beta.3 → 0.0.31-beta.4

package/AGENTS.md

@@ -4,9 +4,9 @@ This document explains how code-generation agents should use this library safely
 
 Full guidance has been split out for progressive loading:
 
-- **Global guidelines** (exports, hard rules, code block rendering, style utilities, theme authoring, `isEmpty`, code gen patterns, fallback strategy): see the [craftsman-component-usage skill](.github/skills/craftsman-component-usage/SKILL.md).
+- **Global guidelines** (exports, hard rules, code block rendering, style utilities, theme authoring, `isEmpty`, code gen patterns, fallback strategy): see the [craftsman-component-usage skill](skills/craftsman-component-usage/SKILL.md).
 - **Component-specific guidelines** (props, behavior notes, examples): each component has its own `AGENTS.md` co-located with its source, for example [src/components/Button/AGENTS.md](src/components/Button/AGENTS.md).
-- **Device/browser detection** (prefer `react-device-detect` over custom user-agent/viewport checks): see the [craftsman-device-detection skill](.github/skills/craftsman-device-detection/SKILL.md).
+- **Device/browser detection** (prefer `react-device-detect` over custom user-agent/viewport checks): see the [craftsman-device-detection skill](skills/craftsman-device-detection/SKILL.md).
 
 ## Quick Reference
 
@@ -41,9 +41,9 @@ Do not assume a root export like `@stamcat/craftsman` unless that export is expl
 
 ## Hard Rules for Agents
 
-1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`).
+1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`). This applies to Sass too — `@use "@stamcat/craftsman/src/styles/utilities/functions"` will fail to resolve; use the published subpath `@stamcat/craftsman/styles/utilities/functions` instead.
 2. Only use documented component entry points.
-3. Do not import storybook files or internal style utilities from consuming applications.
+3. Do not import storybook files from consuming applications. Style utilities are fine to import, but only via their published subpaths (`@stamcat/craftsman/styles/utilities/functions`, `/mixins`, `/placeholders`) — never via a `/src/...` path.
 4. Prefer standard React props first; use custom props only when required.
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stamcat/craftsman",
-  "version": "0.0.31-beta.3",
+  "version": "0.0.31-beta.4",
   "type": "module",
   "description": "A powerful, lightweight framework for design systems",
   "repository": {
@@ -16,6 +16,8 @@
   "bugs": {
     "url": "https://github.com/Stamcat/craftsman/issues"
   },
+  "x-agent-instructions": "./AGENTS.md",
+  "x-agent-components": "./src/components/*/AGENTS.md",
   "types": "./src/components/index.d.ts",
   "main": "./Components.esm.js",
   "homepage": "https://github.com/Stamcat/craftsman#readme",

package/skills/craftsman-component-usage/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: craftsman-component-usage
+description: 'Global AI agent guidelines for using the @stamcat/craftsman component library — package exports, hard import rules, code block rendering, Toast usage, and code generation patterns. Use when generating or reviewing code that imports from @stamcat/craftsman or needing per-component prop contracts (Button, Input, Modal, DatePicker, TimePicker, Carousel, Pagination, etc). See the craftsman-style-utilities, craftsman-utility-functions, and craftsman-device-detection skills for styling, utility function, and device detection guidance.'
+---
+
+# Craftsman Component Library Usage
+
+Global rules for AI agents generating code against `@stamcat/craftsman`. For a specific component's props, behavior notes, and examples, open that component's `AGENTS.md` co-located with its source — see the index below. For styling utilities and theme authoring, see the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md). For the `isEmpty` utility and style utility parity notes, see the [craftsman-utility-functions skill](../craftsman-utility-functions/SKILL.md). For device/browser/OS detection, see the [craftsman-device-detection skill](../craftsman-device-detection/SKILL.md).
+
+## What This Package Currently Exports
+
+The package is built with component-level entry points only.
+
+```tsx
+import { Button } from "@stamcat/craftsman/Button";
+import { Carousel } from "@stamcat/craftsman/Carousel";
+import { Checkbox } from "@stamcat/craftsman/Checkbox";
+import { DatePicker } from "@stamcat/craftsman/DatePicker";
+import { DateRangePicker } from "@stamcat/craftsman/DateRangePicker";
+import { Input } from "@stamcat/craftsman/Input";
+import { InputNumber } from "@stamcat/craftsman/InputNumber";
+import { InputPassword } from "@stamcat/craftsman/InputPassword";
+import { InputPhone } from "@stamcat/craftsman/InputPhone";
+import { Loader } from "@stamcat/craftsman/Loader";
+import { Modal } from "@stamcat/craftsman/Modal";
+import { Pagination } from "@stamcat/craftsman/Pagination";
+import { RadioButton } from "@stamcat/craftsman/RadioButton";
+import { Select } from "@stamcat/craftsman/Select";
+import { Text } from "@stamcat/craftsman/Text";
+import { Textarea } from "@stamcat/craftsman/Textarea";
+import { TimePicker } from "@stamcat/craftsman/TimePicker";
+import { DateTimePicker } from "@stamcat/craftsman/DateTimePicker";
+import { Toggle } from "@stamcat/craftsman/Toggle";
+import { Tooltip } from "@stamcat/craftsman/Tooltip";
+import { Notice } from "@stamcat/craftsman/Notice";
+import { SortableList } from "@stamcat/craftsman/SortableList";
+```
+
+Do not assume a root export like `@stamcat/craftsman` unless that export is explicitly added to package `exports`.
+
+## Hard Rules for Agents
+
+1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`). This applies to Sass too — `@use "@stamcat/craftsman/src/styles/utilities/functions"` will fail to resolve; use the published subpath `@stamcat/craftsman/styles/utilities/functions` instead.
+2. Only use documented component entry points.
+3. Do not import storybook files from consuming applications. Style utilities are fine to import, but only via their published subpaths (`@stamcat/craftsman/styles/utilities/functions`, `/mixins`, `/placeholders`) — never via a `/src/...` path.
+4. Prefer standard React props first; use custom props only when required.
+
+## Component Index
+
+Each entry links to the `AGENTS.md` co-located with that component's source for props, behavior notes, and examples.
+
+| Component | Docs |
+|---|---|
+| Button | [../../src/components/Button/AGENTS.md](../../src/components/Button/AGENTS.md) |
+| Input | [../../src/components/Input/AGENTS.md](../../src/components/Input/AGENTS.md) |
+| InputPassword | [../../src/components/InputPassword/AGENTS.md](../../src/components/InputPassword/AGENTS.md) |
+| Checkbox | [../../src/components/Checkbox/AGENTS.md](../../src/components/Checkbox/AGENTS.md) |
+| RadioButton | [../../src/components/RadioButton/AGENTS.md](../../src/components/RadioButton/AGENTS.md) |
+| Modal | [../../src/components/Modal/AGENTS.md](../../src/components/Modal/AGENTS.md) |
+| Pagination | [../../src/components/Pagination/AGENTS.md](../../src/components/Pagination/AGENTS.md) |
+| Carousel | [../../src/components/Carousel/AGENTS.md](../../src/components/Carousel/AGENTS.md) |
+| Loader | [../../src/components/Loader/AGENTS.md](../../src/components/Loader/AGENTS.md) |
+| Textarea | [../../src/components/Textarea/AGENTS.md](../../src/components/Textarea/AGENTS.md) |
+| Select | [../../src/components/Select/AGENTS.md](../../src/components/Select/AGENTS.md) |
+| InputPhone | [../../src/components/InputPhone/AGENTS.md](../../src/components/InputPhone/AGENTS.md) |
+| DatePicker | [../../src/components/DatePicker/AGENTS.md](../../src/components/DatePicker/AGENTS.md) |
+| DateRangePicker | [../../src/components/DateRangePicker/AGENTS.md](../../src/components/DateRangePicker/AGENTS.md) |
+| InputNumber | [../../src/components/InputNumber/AGENTS.md](../../src/components/InputNumber/AGENTS.md) |
+| TimePicker | [../../src/components/TimePicker/AGENTS.md](../../src/components/TimePicker/AGENTS.md) |
+| Text | [../../src/components/Text/AGENTS.md](../../src/components/Text/AGENTS.md) |
+| DateTimePicker | [../../src/components/DateTimePicker/AGENTS.md](../../src/components/DateTimePicker/AGENTS.md) |
+| Tooltip | [../../src/components/Tooltip/AGENTS.md](../../src/components/Tooltip/AGENTS.md) |
+| Toggle | [../../src/components/Toggle/AGENTS.md](../../src/components/Toggle/AGENTS.md) |
+| Notice | [../../src/components/Notice/AGENTS.md](../../src/components/Notice/AGENTS.md) |
+| SortableList | [../../src/components/SortableList/AGENTS.md](../../src/components/SortableList/AGENTS.md) |
+
+Not yet part of the documented public export surface: `Progress` (source exists but is incomplete — see Known Limitations).
+
+## Code Block Rendering
+
+Craftsman's global styles automatically style `<code>` and `<code><pre>` elements. **Never create custom inline styles or wrapper divs to simulate a code block.** Use the native elements directly:
+
+```tsx
+// Inline code — renders with pill/badge style
+<code>someValue</code>
+
+// Block code — renders with dark background, padding, and border-radius
+<code><pre>{`your
+multiline
+code here`}</pre></code>
+```
+
+The two modes are driven by `_code.scss`:
+- `<code>` alone → light gray background, inline display
+- `<code>` containing `<pre>` → dark background (`--gray800`), block display, padded and rounded
+
+Do not create `preStyle`, `codeBlockStyle`, or equivalent inline style objects for this purpose. The global styles handle it.
+
+## Toast (react-toastify)
+
+Craftsman re-exports `toast` and `ToastContainer` from `react-toastify`. No custom wrapper is needed, and there is no dedicated component folder for it.
+
+Import:
+
+```tsx
+import { toast, ToastContainer } from "react-toastify";
+import "react-toastify/dist/ReactToastify.css";
+```
+
+Usage:
+
+- Render one `<ToastContainer>` near the root of your app.
+- Call `toast(...)` anywhere in response to user actions.
+- `ToastContainer` props: `position`, `autoClose`, `theme` (`"light" | "dark" | "colored"`), `closeOnClick`, `pauseOnHover`, `draggable`, `newestOnTop`.
+
+Example:
+
+```tsx
+// Root layout
+<ToastContainer position="bottom-right" autoClose={3000} theme="light" />
+
+// Anywhere in the app
+toast("Saved successfully!");
+toast.error("Something went wrong.");
+toast.success("Profile updated.");
+toast.warning("Unsaved changes.");
+toast.info("New version available.");
+```
+
+## Code Generation Patterns to Prefer
+
+1. Generate fully typed React usage examples.
+2. Keep accessibility props in place (`aria-label`, `disabled`, semantic `type`).
+3. Use `variant="primary"` for main actions and `variant="text"` for low-emphasis actions.
+4. For loading states, pair `Loader` with accessible status text where needed.
+5. **Functional component declaration order** — always organize the body in this sequence:
+   1. Hook calls (`useSomething`)
+   2. State (`useState`)
+   3. Derived state / variables (values computed from state or props)
+   4. Action handlers (`const handle*`, `const dispatch*`, `useEffect`)
+
+## Known Limitations (Current Package State)
+
+1. The README now covers installation, theming, and getting-started usage; treat this skill and the per-component `AGENTS.md` files as the source of truth for deeper agent usage.
+2. Theme utilities exist in source but are not guaranteed public package exports.
+3. `Progress` exists in source but is incomplete and intentionally omitted from documentation for now.
+
+## Safe Fallback Strategy for Agents
+
+If uncertain about available exports:
+
+1. Use only `Button`, `Checkbox`, `DatePicker`, `Input`, `InputPassword`, `InputPhone`, `Loader`, `Modal`, `RadioButton`, `Select`, `Text`, and `Textarea` from their component entry points.
+2. Do not invent package APIs.
+3. Prefer native HTML elements for anything not explicitly exported.

package/skills/craftsman-device-detection/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: craftsman-device-detection
+description: 'Device/browser detection conventions for @stamcat/craftsman — use react-device-detect instead of hand-rolled user-agent sniffing or window.innerWidth checks. Use when writing responsive logic, conditional rendering by device/browser/OS, or reviewing code that branches on viewport size or navigator.userAgent.'
+---
+
+# Craftsman Device Detection
+
+`react-device-detect` is already a dependency of `@stamcat/craftsman` (it powers the mobile wheel-picker fallback in `TimePicker`). **Prefer it over custom implementations** for any device, browser, or OS branching logic. Consuming apps should install it directly rather than writing their own detection.
+
+## Hard Rule
+
+Never write custom detection logic such as:
+
+```ts
+// DO NOT — fragile, reinvents an already-solved problem
+const isMobile = /Mobi|Android/i.test(navigator.userAgent);
+const isMobile = window.innerWidth < 768;
+```
+
+Use the library instead:
+
+```tsx
+import { isMobile } from "react-device-detect";
+
+if (isMobile) {
+    // mobile-specific behavior
+}
+```
+
+CSS media queries are still the right tool for pure layout/visual breakpoints (see the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md) for `breakpoint()`). Reach for `react-device-detect` when the decision depends on the actual device/browser/OS rather than viewport width alone, or when the branch happens in JS/TS rather than CSS.
+
+## Common Named Exports
+
+```tsx
+import {
+    isMobile,
+    isTablet,
+    isDesktop,
+    isBrowser,
+    isSmartTV,
+    isAndroid,
+    isIOS,
+    isMobileOnly,
+    browserName,
+    osName,
+    deviceType,
+    BrowserView,
+    MobileView,
+    TabletView,
+} from "react-device-detect";
+```
+
+- `isMobile` / `isTablet` / `isDesktop` / `isBrowser` — boolean flags for conditional logic.
+- `isMobileOnly` — `true` for phones, `false` for tablets (use this, not `isMobile`, when tablets must be excluded).
+- `browserName`, `osName`, `deviceType` — string values for logging/analytics, not for branching (prefer the boolean flags for that).
+- `BrowserView` / `MobileView` / `TabletView` — declarative wrapper components that render `children` only on the matching device, as an alternative to `if (isMobile)` branches in JSX.
+
+## Example: Conditional Rendering
+
+```tsx
+import { MobileView, BrowserView } from "react-device-detect";
+
+<MobileView>
+    <CompactNav />
+</MobileView>
+<BrowserView>
+    <FullNav />
+</BrowserView>
+```
+
+## Orientation
+
+For portrait/landscape detection, use the `useMobileOrientation` hook rather than comparing `window.innerWidth`/`innerHeight`:
+
+```tsx
+import { useMobileOrientation } from "react-device-detect";
+
+const { isPortrait, isLandscape } = useMobileOrientation();
+```

package/skills/craftsman-style-utilities/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: craftsman-style-utilities
+description: 'Styling conventions for @stamcat/craftsman — color()/width()/breakpoint() TypeScript and Sass helpers, styling expectations, and theme authoring (theme.root, theme.components, theme.widths). Use when writing styles, CSS-in-JS, Sass, or ThemeProvider theme objects for @stamcat/craftsman.'
+---
+
+# Craftsman Style Utilities
+
+Styling rules for AI agents generating code against `@stamcat/craftsman`. For package exports, hard rules, and component contracts, see the [craftsman-component-usage skill](../craftsman-component-usage/SKILL.md). For non-styling utility functions (`isEmpty`), see the [craftsman-utility-functions skill](../craftsman-utility-functions/SKILL.md).
+
+## Sass Import Path (hard rule)
+
+Always `@use` the published subpath — never deep-import the source file directly.
+
+```scss
+// Correct
+@use "@stamcat/craftsman/styles/utilities/functions" as u;
+@use "@stamcat/craftsman/styles/utilities/mixins" as m;
+@use "@stamcat/craftsman/styles/utilities/placeholders";
+
+// Wrong — not an exported subpath, will fail to resolve at build time
+@use "@stamcat/craftsman/src/styles/utilities/functions" as u;
+```
+
+## Style Utilities
+
+Craftsman provides TypeScript helpers and matching Sass functions for color, spacing, and breakpoints. Always use these instead of hard-coded values so theming and overrides work correctly.
+
+### color()
+
+**TypeScript** — import from `@stamcat/craftsman/styles`:
+
+```ts
+import { color, colors, hexToRgba } from "@stamcat/craftsman/styles";
+
+// Returns var(--blue500)
+color("blue500")
+
+// Returns rgb(from var(--blue500) r g b / 0.5)
+color("blue500", "rgba", 0.5)
+
+// Fallback for environments that don't support CSS relative color syntax
+hexToRgba(colors.blue500, 0.5)
+```
+
+**Sass** — import `functions` as `u`:
+
+```scss
+@use "@stamcat/craftsman/styles/utilities/functions" as u;
+
+.element {
+  color:      #{u.color(blue500)};
+  background: #{u.color(black, rgba, 0.4)};
+}
+```
+
+- `color(name)` → `var(--name)` — always prefer this over hard-coded hex values so theme overrides apply.
+- `color(name, rgba, alpha)` → `rgb(from var(--name) r g b / alpha)` — uses CSS relative color syntax; verify browser support for your target.
+- Never hard-code hex color values. Always use `color()` or a CSS variable.
+
+### width()
+
+**TypeScript** — import from `@stamcat/craftsman/styles`:
+
+```ts
+import { width } from "@stamcat/craftsman/styles";
+
+width("gutter")        // var(--w-gutter, 16px)
+width("gutter", 0.5)   // calc(var(--w-gutter, 16px) * 0.5)
+width("column", 3)     // calc((var(--w-column) * 3) + (var(--w-gutter) * 2))
+```
+
+**Sass** — import `functions` as `u`:
+
+```scss
+@use "@stamcat/craftsman/styles/utilities/functions" as u;
+
+.card {
+  padding:   #{u.width(gutter)};
+  gap:       #{u.width(gutter, 0.5)};
+  max-width: #{u.width(column, 4)};
+}
+```
+
+Valid keys: `text` · `gutter` · `column` · `tablet` · `desktop` · `extDesktop` · `mobileMax` · `tabletMax` · `desktopMax`
+
+- The `column` key automatically accounts for gutters between columns.
+- Never use hard-coded `px` values for spacing or layout widths. Always use `width()`.
+
+### breakpoint()
+
+**TypeScript** — returns a full `@media` rule string for CSS-in-JS:
+
+```ts
+import { breakpoint, media } from "@stamcat/craftsman/styles";
+
+// Full rule — use inside styled-components, emotion, or style injection
+breakpoint("desktop", "font-size: 18px;")
+// => "@media (min-width: 1040px) { font-size: 18px; }"
+
+// Raw query string only — use for conditional logic or matchMedia
+media.tablet  // => "(min-width: 660px)"
+```
+
+**Sass** — `@include breakpoint(key)` wraps content in the correct `@media` query:
+
+```scss
+@use "@stamcat/craftsman/styles/utilities/functions" as u;
+
+.sidebar {
+  display: none;
+
+  @include u.breakpoint(tablet) {
+    display: block;
+  }
+}
+```
+
+Available breakpoint keys: `tablet` · `tabletMax` · `tabletOnly` · `desktop` · `desktopMax` · `desktopOnly` · `extDesktop` · `mobileMax` · `mobileOnly` · `mobileTablet`
+
+- Breakpoint values come from `_config.scss` and stay in sync with any project overrides.
+- Never hard-code `@media (min-width: 1040px)` or similar — always use `breakpoint()` so values stay consistent with config.
+
+## Styling Expectations
+
+- Components are built with SCSS modules and class-based variant hooks.
+- If your app does not include this package's global CSS variable setup, visual output may differ.
+- Agents should avoid hard-coding assumptions about token names beyond what the consumer app already defines.
+
+## Custom Sizing / Scale Props
+
+When a component accepts a numeric size/scale prop (for example `Button`'s `size` or `Toggle`'s `width`), the component sets **one** CSS custom property inline (only when the prop is provided), and the SCSS file does all the `calc()` math from there:
+
+```tsx
+// Component: only ever set the single scale variable
+const sizeStyle = normalizedSize ? ({ "--btn-size": normalizedSize } as React.CSSProperties) : undefined;
+```
+
+```scss
+// SCSS: give the variable a default, then derive every scaled property from it
+%button-styles {
+  --btn-size: 1;
+  padding: calc(#{u.width(gutter, 0.5)} * var(--btn-size)) calc(#{u.width(gutter, 0.75)} * var(--btn-size));
+  border-radius: calc(#{u.width(gutter, 0.75)} * var(--btn-size));
+  font-size: max(10px, calc(#{u.width(text)} * var(--btn-size)));
+}
+```
+
+Do not compute `calc()` strings per-property in JS/TS (for example building a `padding: "calc(... * 1.5)"` string in the component). Always push that math into SCSS and only pass the raw scale/size value through a single CSS variable.
+
+## Theme Authoring
+
+- `theme.root` supports JS style objects and raw CSS/Sass strings.
+- `theme.components.*` supports JS style objects and raw CSS/Sass strings.
+- `theme.widths` accepts a partial record of width/breakpoint keys to override the default `--w-*` CSS variables. Values are numbers in `px`.
+- String component styles are applied to the mapped target selector (for example `button`, `input[type='checkbox']`).
+- For multi-file Sass workflows with syntax highlighting and mixins, import compiled CSS text via `*.scss?inline`.
+
+Valid `theme.widths` keys: `"text" | "gutter" | "column" | "tablet" | "desktop" | "extDesktop" | "mobileMax" | "tabletMax" | "desktopMax"`
+
+Example:
+
+```tsx
+import greenRoot from "./green.root.scss?inline";
+import greenButton from "./green.button.scss?inline";
+
+export const theme = {
+  widths: {
+    gutter: 20,
+    tablet: 768,
+  },
+  root: greenRoot,
+  components: {
+    button: greenButton,
+  },
+};
+```

package/skills/craftsman-utility-functions/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: craftsman-utility-functions
+description: 'Utility function conventions for @stamcat/craftsman — the isEmpty validation helper and TypeScript/Sass parity for style utility patterns. Use when writing empty/falsy checks or referencing color()/width()/breakpoint() usage patterns for @stamcat/craftsman.'
+---
+
+# Craftsman Utility Functions
+
+Non-styling utility function rules for AI agents generating code against `@stamcat/craftsman`. For package exports, hard rules, and component contracts, see the [craftsman-component-usage skill](../craftsman-component-usage/SKILL.md). For styling and theme authoring, see the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md).
+
+## `isEmpty`
+
+The package exports an `isEmpty` utility. **Always use it instead of writing inline empty checks.**
+
+Import:
+
+```ts
+import { isEmpty } from "@stamcat/craftsman/utilities/validations";
+```
+
+It returns `true` for:
+
+- `undefined`
+- `null`
+- empty objects — `{}`
+- strings that are empty or whitespace-only — `""`, `" "`
+- arrays with no elements — `[]`
+
+Examples:
+
+```ts
+// DO — use isEmpty
+if (isEmpty(value)) { ... }
+if (!isEmpty(items)) { ... }
+
+// DO NOT — write these manually
+if (value === undefined || value === null) { ... }
+if (typeof value === "string" && value.trim().length === 0) { ... }
+if (Object.keys(obj).length === 0) { ... }
+if (arr.length === 0) { ... }
+```
+
+## Style utilities parity (`color`, `width`, `breakpoint`)
+
+These utility patterns exist in both TypeScript and Sass. See the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md) for full usage details.
+
+TypeScript usage:
+
+```ts
+import { color, width, breakpoint } from "@stamcat/craftsman/styles";
+
+const accent = color("blue500");
+const alphaAccent = color("blue500", "rgba", 0.32);
+const twoColumns = width("column", 2);
+const mobileRule = breakpoint("mobileMax", "h4{font-size:14px;}");
+```
+
+Sass usage (framework source):
+
+```scss
+@use "./src/styles/utilities" as u;
+
+.example {
+  color: #{u.color(blue500)};
+  background: #{u.color(blue500, rgba, 0.32)};
+  max-width: #{u.width(column, 2)};
+}
+
+@include u.breakpoint(mobileMax) {
+  .example { font-size: #{u.width(text)}; }
+}
+```