@stamcat/craftsman 0.0.27-alpha.2 → 0.0.27-alpha.21

package/src/components/Notice/AGENTS.md

@@ -0,0 +1,42 @@
+# Notice — Agent Usage Notes
+
+Import:
+
+```tsx
+import { Notice } from "@stamcat/craftsman/Notice";
+```
+
+Props:
+
+- Inherits all native `<div>` props.
+- `type?: "help" | "info" | "success" | "error" | "none"` (default: `"info"`; `"none"` hides the leading status icon container)
+- `icon?: React.ReactNode` (overrides the default status icon for the given `type`)
+- `title?: string | React.ReactNode`
+- `message?: string | React.ReactNode`
+- `children?: React.ReactNode` (rendered alongside `title`/`message`)
+- `buttons?: React.ReactNode` (rendered in a footer action row)
+- `dismissible?: boolean` (shows a close ("x") button)
+- `visible?: boolean` (default: `true`; renders nothing when `false`)
+- `onDismiss?: (id?: string) => void`
+- `id?: string` (passed back to `onDismiss`)
+
+Behavior notes:
+
+- Notice is an inline, persistent alert banner — not a popup toast. For transient popup notifications use the existing `react-toastify` integration (see the "Molecules/Toast" story), not this component.
+- Notice is not self-dismissing — the dismiss button only calls `onDismiss`; the parent owns visibility and must flip `visible` to `false` (or unmount) in response.
+- `title` is wrapped in `<Text as="h5">` and `message` in `<Text as="span">` when passed as a string; `React.ReactNode` values are rendered as-is.
+- The leading icon inherits its color via CSS (`currentColor`) from the `.notice.<type>` class — don't pass an explicit `fill`/`color` prop to override it, use `icon` to swap the element instead.
+
+Example:
+
+```tsx
+<Notice
+  type="error"
+  title="Something went wrong"
+  message="Please check the highlighted fields and try again."
+  dismissible
+  visible={visible}
+  onDismiss={() => setVisible(false)}
+  buttons={<Button variant="text" onClick={retry}>Retry</Button>}
+/>
+```

package/src/components/Notice/Notice.css

@@ -0,0 +1 @@
+@layer craftsman-component{.notice{gap:calc(var(--w-gutter) * .5);padding:var(--w-gutter);border:1px solid var(--gray400);background-color:var(--white);border-left-width:3px;border-radius:4px;flex-direction:column;transition:opacity .5s ease-in-out;display:flex}.notice.info{border-color:var(--blue500);background-color:var(--blue50);color:var(--blue600)}.notice.success{border-color:var(--green500);background-color:var(--green50);border-color:var(--green500)}.notice.error{border-color:var(--red500);background-color:var(--red50);color:var(--red600)}.notice.help{border-color:var(--gray500);background-color:var(--gray50)}.notice button.text{color:inherit}.notice-contents{align-items:flex-start;gap:calc(var(--w-gutter) * .5);flex-flow:row;width:100%;display:flex}.notice-icon{flex:none;font-size:24px;display:flex}.notice-text{margin-top:calc(var(--w-gutter) * .25);flex-grow:1}.notice-text span{display:block}.notice-dismiss{flex:none;padding:0}.notice-buttons{justify-content:flex-end;gap:calc(var(--w-gutter) * .5);width:100%;display:flex}}

package/src/components/Notice/Notice.d.ts

@@ -0,0 +1,13 @@
+import { NoticeType } from '../../utilities/types';
+export type NoticeProps = React.ComponentPropsWithoutRef<"div"> & {
+    type?: NoticeType;
+    icon?: React.ReactNode;
+    title?: string | React.ReactNode;
+    message?: string | React.ReactNode;
+    buttons?: React.ReactNode;
+    visible?: boolean;
+    dismissible?: boolean;
+    onDismiss?: (id?: string) => void;
+    id?: string;
+};
+export declare const Notice: React.FC<NoticeProps>;

package/src/components/Notice/Notice.scss

@@ -0,0 +1,76 @@
+@use "../../styles/utilities/_functions" as u;
+
+@layer craftsman-component {
+    .notice {
+        transition: opacity 500ms ease-in-out;
+        display: flex;
+        flex-direction: column;
+        gap: #{u.width("gutter", 0.5)};
+        padding: #{u.width("gutter")};
+        border: 1px solid var(--gray400);
+        border-left-width: 3px;
+        background-color: var(--white);
+        border-radius: 4px;
+
+        &.info {
+            border-color: var(--blue500);
+            background-color: var(--blue50);
+            color: var(--blue600);
+        }
+
+        &.success {
+            border-color: var(--green500);
+            background-color: var(--green50);
+            border-color: var(--green500);
+        }
+
+        &.error {
+            border-color: var(--red500);
+            background-color: var(--red50);
+            color: var(--red600);
+        }
+
+        &.help {
+            border-color: var(--gray500);
+            background-color: var(--gray50);
+        }
+        button.text {
+            color: inherit;
+        }
+    }
+
+    .notice-contents {
+        display: flex;
+        flex-flow: row nowrap;
+        align-items: flex-start;
+        gap: #{u.width("gutter", 0.5)};
+        width: 100%;
+    }
+
+    .notice-icon {
+        display: flex;
+        flex: 0 0 auto;
+        font-size: 24px;
+    }
+
+    .notice-text {
+        flex-grow: 1;
+        margin-top: #{u.width("gutter", 0.25)};
+        span {
+            display: block;
+        }
+    }
+
+    .notice-dismiss {
+        flex: 0 0 auto;
+        padding: 0;
+    }
+
+    .notice-buttons {
+        width: 100%;
+        display: flex;
+        justify-content: flex-end;
+        gap: #{u.width("gutter", 0.5)};
+       
+    }
+}

package/src/components/Notice/Notice2.esm.js

@@ -0,0 +1,56 @@
+"use client";
+import { Button as e } from "../Button/Button.esm.js";
+import { Text as t } from "../Text/Text2.esm.js";
+import './Notice.css';/* empty css           */
+import n from "clsx";
+import { Fragment as r, jsx as i, jsxs as a } from "react/jsx-runtime";
+import { IoAlertCircleOutline as o, IoCheckmarkCircleOutline as s, IoCloseOutline as c, IoHelpCircleOutline as l, IoInformationCircleOutline as u } from "react-icons/io5";
+//#region src/components/Notice/Notice.tsx
+var d = {
+	info: /* @__PURE__ */ i(u, {}),
+	success: /* @__PURE__ */ i(s, {}),
+	error: /* @__PURE__ */ i(o, {}),
+	help: /* @__PURE__ */ i(l, {}),
+	none: /* @__PURE__ */ i(r, {})
+}, f = (e, n) => typeof e == "string" ? /* @__PURE__ */ i(t, {
+	as: n,
+	children: e
+}) : e, p = ({ type: t = "info", title: r, message: o, buttons: s, id: l, className: u, style: p, icon: m, children: h, dismissible: g, onDismiss: _, ...v }) => {
+	let y = () => {
+		_?.(l);
+	};
+	return /* @__PURE__ */ a("div", {
+		id: l,
+		className: n("notice", t, u),
+		style: p,
+		...v,
+		children: [/* @__PURE__ */ a("div", {
+			className: "notice-contents",
+			children: [
+				t !== "none" && /* @__PURE__ */ i("div", {
+					className: "notice-icon",
+					children: m || d[t]
+				}),
+				/* @__PURE__ */ a("div", {
+					className: "notice-text",
+					children: [
+						r && f(r, "h5"),
+						o && f(o, "span"),
+						h
+					]
+				}),
+				g && /* @__PURE__ */ i(e, {
+					variant: "text",
+					className: "notice-dismiss",
+					onClick: y,
+					children: /* @__PURE__ */ i(c, { size: 16 })
+				})
+			]
+		}), s && /* @__PURE__ */ i("footer", {
+			className: "notice-buttons",
+			children: s
+		})]
+	});
+};
+//#endregion
+export { p as Notice };

package/src/components/Pagination/AGENTS.md

@@ -0,0 +1,38 @@
+# Pagination — Agent Usage Notes
+
+Import:
+
+```tsx
+import { Pagination } from "@stamcat/craftsman/Pagination";
+```
+
+Props:
+
+- `total: number`
+- `current: number`
+- `showPages?: number` (default: `5`)
+- `onChange: (e: React.MouseEvent<HTMLButtonElement>) => void`
+- `className?: string`
+- `style?: React.CSSProperties`
+
+Behavior notes:
+
+- Pagination is zero-based internally. Pass `current={0}` for the first page.
+- `total` is the total number of pages, not the last page index.
+- The component renders first/last buttons and jump-by-window buttons when needed.
+- `showPages` controls both the visible window size and the jump step for `‹‹` / `››`.
+- `onChange` receives the clicked button event. Read the next page from `event.currentTarget.value`.
+- The active page button is disabled and marked with `aria-current="page"`.
+
+Example:
+
+```tsx
+const [current, setCurrent] = useState(0);
+
+<Pagination
+  total={50}
+  current={current}
+  showPages={5}
+  onChange={(event) => setCurrent(parseInt(event.currentTarget.value, 10) || 0)}
+/>
+```

package/src/components/Pagination/Pagination.css

@@ -0,0 +1 @@
+@layer craftsman-component{.pagination{align-items:center;gap:calc(var(--w-gutter) * .25);display:inline-flex}.pagination .active{color:var(--gray700);border:1px solid;border-radius:50%;justify-content:center;align-items:center;width:20px;height:20px;display:inline-flex}}

package/src/components/Pagination/Pagination.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+export type PaginationProps = {
+    total: number;
+    current: number;
+    showPages?: number;
+    onChange: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    className?: string;
+    style?: React.CSSProperties;
+};
+export declare const Pagination: React.FC<PaginationProps>;

package/src/components/Pagination/Pagination.scss

@@ -0,0 +1,22 @@
+
+@use "../../styles/utilities/_functions" as u;
+
+@layer craftsman-component {
+    .pagination {
+        display: inline-flex;
+        align-items: center;
+        gap: #{u.width("gutter", 0.25)};
+
+        .active {
+            color: #{u.color("gray700")};
+            border: 1px solid;
+            border-radius: 50%;
+            width: 20px;
+            height: 20px;
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            
+        }
+    }
+}

package/src/components/Pagination/Pagination2.esm.js

@@ -0,0 +1,64 @@
+"use client";
+import './Pagination.css';/* empty css               */
+import e from "clsx";
+import { jsx as t, jsxs as n } from "react/jsx-runtime";
+import "react";
+//#region src/components/Pagination/Pagination.tsx
+var r = ({ total: r, current: i, onChange: a, className: o, style: s, showPages: c = 5 }) => {
+	function l(e, t) {
+		let n = Math.floor(c / 2), r = Math.max(0, e - n), i = Math.min(t - 1, r + c - 1);
+		r = Math.max(0, i - c + 1);
+		let a = [];
+		for (let e = r; e <= i; e++) a.push(e);
+		return a;
+	}
+	let u = l(i, r), d = Math.floor(i / c), f = d > 0, p = (d + 1) * c < r, m = (d - 1) * c, h = (d + 1) * c;
+	return /* @__PURE__ */ n("nav", {
+		className: e("pagination", o),
+		style: s,
+		"aria-label": "Pagination",
+		children: [
+			/* @__PURE__ */ t("button", {
+				className: "text",
+				value: 0,
+				onClick: a,
+				disabled: i === 0,
+				"aria-label": "First page",
+				children: "«"
+			}),
+			f && /* @__PURE__ */ t("button", {
+				className: "text",
+				value: m,
+				onClick: a,
+				"aria-label": `Back ${c} pages`,
+				children: "‹‹"
+			}),
+			u.map((n) => /* @__PURE__ */ t("button", {
+				value: n,
+				onClick: a,
+				disabled: n === i,
+				"aria-label": `Page ${n + 1}`,
+				"aria-current": n === i ? "page" : void 0,
+				className: e("text", n === i ? "active" : void 0),
+				children: n + 1
+			}, n)),
+			p && /* @__PURE__ */ t("button", {
+				className: "text",
+				value: h,
+				onClick: a,
+				"aria-label": `Forward ${c} pages`,
+				children: "››"
+			}),
+			/* @__PURE__ */ t("button", {
+				className: "text",
+				value: r - 1,
+				onClick: a,
+				disabled: i === r - 1,
+				"aria-label": "Last page",
+				children: "»"
+			})
+		]
+	});
+};
+//#endregion
+export { r as Pagination };

package/src/components/RadioButton/AGENTS.md

@@ -0,0 +1,44 @@
+# RadioButton — Agent Usage Notes
+
+Import:
+
+```tsx
+import { RadioButton } from "@stamcat/craftsman/RadioButton";
+```
+
+Props:
+
+- Extends `Input` props.
+- `type?: "radio"` (default: `"radio"`)
+- `labelPosition?: "left" | "right"` (default: `"right"`)
+- `size?: number` (default visual scale is `1`, clamped to `[0.1, 10]`)
+
+Behavior notes:
+
+- `RadioButton` is a thin wrapper around `Input` with radio-specific guardrails.
+- Group behavior is native HTML radio behavior: use a shared `name` across options.
+- Controlled and uncontrolled patterns are both supported (`checked` + `onChange`, or `defaultChecked`).
+- When `size` is provided, RadioButton sets a single `--radio-size` CSS variable inline; the radio circle and dot scale via SCSS `calc()` from that variable (same pattern as `Button`'s `--btn-size` and `Toggle`'s `--toggle-width`).
+
+Example:
+
+```tsx
+<>
+  <RadioButton
+    id="captain-kirk"
+    name="favorite-captain"
+    value="Kirk"
+    label="James T. Kirk"
+    checked={selected === "Kirk"}
+    onChange={(event) => setSelected(event.currentTarget.value)}
+  />
+  <RadioButton
+    id="captain-picard"
+    name="favorite-captain"
+    value="Picard"
+    label="Jean-Luc Picard"
+    checked={selected === "Picard"}
+    onChange={(event) => setSelected(event.currentTarget.value)}
+  />
+</>
+```

package/src/components/RadioButton/RadioButton.d.ts

@@ -0,0 +1,9 @@
+import { RadioLabelPosition } from '../../styles';
+import { InputProps } from '../Input/Input';
+type RadioButtonProps = InputProps & {
+    type?: "radio";
+    labelPosition?: RadioLabelPosition;
+    size?: number;
+};
+export declare const RadioButton: React.FC<RadioButtonProps>;
+export {};

package/src/components/RadioButton/RadioButton.esm.js

@@ -0,0 +1,18 @@
+"use client";
+import { Input as e } from "../Input/Input2.esm.js";
+import { jsx as t } from "react/jsx-runtime";
+//#region src/components/RadioButton/RadioButton.tsx
+var n = ({ type: n = "radio", labelPosition: r = "right", size: i, style: a, ...o }) => {
+	let s = typeof i == "number" ? Math.min(10, Math.max(.1, i)) : void 0;
+	return /* @__PURE__ */ t(e, {
+		type: n,
+		labelPosition: r,
+		style: {
+			...s ? { "--radio-size": s } : void 0,
+			...a
+		},
+		...o
+	});
+};
+//#endregion
+export { n as RadioButton };

package/src/components/Select/AGENTS.md

@@ -0,0 +1,36 @@
+# Select — Agent Usage Notes
+
+Import:
+
+```tsx
+import { Select } from "@stamcat/craftsman/Select";
+```
+
+Props:
+
+- Inherits all native `<select>` props.
+- `label?: string | ReactNode`
+- `labelPosition?: "top" | "left" | "bottom" | "right" | "inside" | "hidden"` (default: `"top"`)
+- `error?: string | boolean | ReactNode`
+- `required?: boolean`
+- `options?: Array<{ label: string; value: string }>`
+
+Behavior notes:
+
+- Built on the native `<select>` element via `InputWrapper`.
+- Pass options as a plain array — do not render `<option>` children manually.
+- `id` is auto-generated via `useId` if not provided.
+
+Example:
+
+```tsx
+<Select
+  label="Favorite Fruit"
+  required
+  options={[
+    { value: "", label: "Select one..." },
+    { value: "apple", label: "Apple" },
+    { value: "banana", label: "Banana" },
+  ]}
+/>
+```

package/src/components/Select/Select.d.ts

@@ -0,0 +1,14 @@
+import { LabeledInput } from '../Input/InputWrapper';
+export type SelectOption = {
+    value: string;
+    selected?: boolean;
+    disabled?: boolean;
+    label: string;
+};
+export type SelectProps = React.ComponentProps<"select"> & LabeledInput & {
+    options?: {
+        label: string;
+        value: string;
+    }[];
+};
+export declare const Select: React.FC<SelectProps>;

package/src/components/Select/Select.esm.js

@@ -0,0 +1,26 @@
+"use client";
+import { InputWrapper as e } from "../Input/InputWrapper.esm.js";
+import { jsx as t } from "react/jsx-runtime";
+import { useId as n } from "react";
+//#region src/components/Select/Select.tsx
+var r = ({ label: r, id: i, labelPosition: a = "top", required: o = !1, error: s, options: c = [], className: l, style: u, ...d }) => {
+	let f = n(), p = i || f;
+	return /* @__PURE__ */ t(e, {
+		label: r,
+		labelPosition: a,
+		error: s,
+		required: o,
+		className: l,
+		style: u,
+		children: /* @__PURE__ */ t("select", {
+			id: p,
+			...d,
+			children: c.map((e, n) => /* @__PURE__ */ t("option", {
+				value: e.value,
+				children: e.label
+			}, `${p}-opt-${n}`))
+		})
+	});
+};
+//#endregion
+export { r as Select };

package/src/components/SortableList/AGENTS.md

@@ -0,0 +1,45 @@
+# SortableList — Agent Usage Notes
+
+Import:
+
+```tsx
+import { SortableList } from "@stamcat/craftsman/SortableList";
+```
+
+Props:
+
+- `items: T[]`
+- `getKey: (item: T, index: number) => string`
+- `renderItem: (args: SortableListRenderArgs<T>) => React.ReactNode`
+- `onReorder: (items: T[]) => void`
+- `disabled?: boolean`
+- `className?: string`
+- `style?: React.CSSProperties`
+
+Behavior notes:
+
+- Built on `@atlaskit/pragmatic-drag-and-drop`. The list only owns drag/drop wiring and reordering — all item markup comes from `renderItem`.
+- `renderItem` receives `{ item, index, isDragging, dropEdge, dragHandleRef }`.
+  - By default the whole rendered item is the drag source.
+  - To restrict dragging to a handle, attach `dragHandleRef` to the handle element's `ref`.
+- `dropEdge` is `"top" | "bottom" | null` while another item is dragged over this one — use it to render a drop indicator, or rely on the built-in `.drop-top` / `.drop-bottom` styles.
+- `onReorder` is called with the full reordered array on drop; the component does not mutate `items` itself — update your own state in the callback.
+- Set `disabled` to suspend all drag/drop wiring (for example while a related request is in flight).
+
+Example:
+
+```tsx
+const [items, setItems] = useState(["Alpha", "Beta", "Gamma"]);
+
+<SortableList
+  items={items}
+  getKey={(item) => item}
+  onReorder={setItems}
+  renderItem={({ item, isDragging, dropEdge, dragHandleRef }) => (
+    <div className={isDragging ? "dragging" : undefined} data-drop-edge={dropEdge ?? undefined}>
+      <span ref={dragHandleRef}>⠿</span>
+      {item}
+    </div>
+  )}
+/>
+```

package/src/components/SortableList/ListItem.d.ts

@@ -0,0 +1,10 @@
+import { SortableListRenderArgs } from './SortableList';
+export type DropEdge = "top" | "bottom";
+export declare function SortableListItem<T>({ item, index, getKey, renderItem, disabled, listId, }: {
+    item: T;
+    index: number;
+    getKey: (item: T, index: number) => string;
+    renderItem: (args: SortableListRenderArgs<T>) => React.ReactNode;
+    disabled?: boolean;
+    listId: string;
+}): import("react").JSX.Element;

package/src/components/SortableList/ListItem.esm.js

@@ -0,0 +1,67 @@
+"use client";
+import { combine as e } from "../../../node_modules/@atlaskit/pragmatic-drag-and-drop/dist/esm/public-utils/combine.esm.js";
+import { draggable as t, dropTargetForElements as n } from "../../../node_modules/@atlaskit/pragmatic-drag-and-drop/dist/esm/adapter/element-adapter.esm.js";
+import { isItemData as r } from "./utilities.esm.js";
+import i from "clsx";
+import { jsx as a } from "react/jsx-runtime";
+import { useEffect as o, useLayoutEffect as s, useRef as c, useState as l } from "react";
+//#region src/components/SortableList/ListItem.tsx
+function u({ item: u, index: d, getKey: f, renderItem: p, disabled: m, listId: h }) {
+	let [g, _] = l(null), [v, y] = l(null), [b, x] = l(!1), [S, C] = l(null), w = c(null), T = c(null), E = f(u, d);
+	return s(() => {
+		w.current = g;
+		let e = w.current;
+		if (!e) return;
+		let t = T.current, n = e.getBoundingClientRect();
+		T.current = n;
+		let r = t ? t.top - n.top : 0;
+		!r || window.matchMedia("(prefers-reduced-motion: reduce)").matches || (e.style.transition = "none", e.style.transform = `translateY(${r}px)`, requestAnimationFrame(() => {
+			e.style.transition = "", e.style.transform = "";
+		}));
+	}, [g, d]), o(() => {
+		if (!g || m) return;
+		let i = {
+			key: E,
+			index: d,
+			listId: h,
+			item: u
+		};
+		return e(t({
+			element: g,
+			dragHandle: v ?? void 0,
+			getInitialData: () => i,
+			onDragStart: () => x(!0),
+			onDrop: () => x(!1)
+		}), n({
+			element: g,
+			getData: () => i,
+			canDrop: ({ source: e }) => r(e.data) && e.data.key !== E,
+			onDrag: ({ location: e }) => {
+				let t = g.getBoundingClientRect(), n = e.current.input.clientY > t.top + t.height / 2;
+				C(n ? "bottom" : "top");
+			},
+			onDragLeave: () => C(null),
+			onDrop: () => C(null)
+		}));
+	}, [
+		g,
+		v,
+		E,
+		d,
+		m,
+		h,
+		u
+	]), /* @__PURE__ */ a("li", {
+		ref: _,
+		className: i("sortable-list-item", b && "dragging", S && `drop-${S}`),
+		children: p({
+			item: u,
+			index: d,
+			isDragging: b,
+			dropEdge: S,
+			dragHandleRef: y
+		})
+	}, E);
+}
+//#endregion
+export { u as SortableListItem };

package/src/components/SortableList/SortableList.css

@@ -0,0 +1 @@
+@layer craftsman-component{.sortable-list{gap:calc(var(--w-gutter) * .25);flex-direction:column;margin:0;padding:0;list-style:none;display:flex}.sortable-list-item{cursor:grab;transition:transform .2s,opacity .15s;position:relative}.sortable-list-item.dragging{opacity:.4}.sortable-list-item.drop-top:before,.sortable-list-item.drop-bottom:after{content:"";background-color:var(--blue500);border-radius:1px;height:2px;position:absolute;left:0;right:0}.sortable-list-item.drop-top:before{top:-1px}.sortable-list-item.drop-bottom:after{bottom:-1px}}

package/src/components/SortableList/SortableList.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+import { DropEdge } from './ListItem';
+export type SortableListItemState = {
+    isDragging: boolean;
+    dropEdge: DropEdge | null;
+};
+export type SortableListRenderArgs<T> = SortableListItemState & {
+    dragHandleRef: (element: HTMLElement | null) => void;
+    item: T;
+    index: number;
+};
+export type SortableListProps<T> = {
+    items: T[];
+    getKey: (item: T, index: number) => string;
+    renderItem: (args: SortableListRenderArgs<T>) => React.ReactNode;
+    onReorder: (items: T[]) => void;
+    disabled?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    listId?: string;
+    onReceive?: (item: T, atIndex: number) => void;
+};
+export declare const SortableList: <T>({ items, getKey, renderItem, onReorder, disabled, className, style, listId, onReceive }: SortableListProps<T>) => React.JSX.Element;