gbs-add-block 2.0.1 → 2.0.3

package/.gbs/skills/gbs-components/references/styling.md

@@ -0,0 +1,182 @@
+# Styling
+
+"Headless" here means the components own behaviour and accessibility and ship a
+default look you can replace at three levels: CSS variables, slot classes, and
+state attributes.
+
+## 1. Stylesheets are per component
+
+Each folder has its own `styles.css`. Put the ones you use in the project's
+**global** stylesheet — `src/index.css` in Vite, the root layout's CSS in Next —
+once each:
+
+```css
+@import "../component-lib/button/styles.css";
+```
+
+**Never import a stylesheet from a component file.** `import
+"component-lib/button/styles.css"` inside a `.tsx` does bundle, but it makes CSS
+order depend on module import order — which decides whether Tailwind utilities
+still beat the component's own rules — and a lazy-loaded component then pulls its
+styles in late, flashing unstyled. One global import per component, nowhere else.
+
+Nothing renders correctly without it — the components emit class names only.
+
+## 2. Theme with `--gbs-*` on `:root`
+
+One set of variables themes every component at once. This is the whole theming
+API; reach for the other levels only when it is not enough.
+
+```css
+:root {
+  --gbs-accent: #7c3aed;
+  --gbs-accent-soft: #f3e8ff;
+  --gbs-radius: 10px;
+  --gbs-font-size: 14px;
+}
+```
+
+Set them on `:root`, not inside a component — components read them through
+inheritance, so anything set on an ancestor reaches every control beneath it.
+
+### Resolution order
+
+Each component variable falls through this chain, stopping at the first set:
+
+1. **The component's own variable** — `--in-accent`, `--dg-accent`, `--ck-border`.
+   Set this to change one component, or one instance.
+2. **The shared variable** — `--gbs-accent`. The one you normally set.
+3. **The DataGrid's variable** — `--dg-accent`, when the grid's stylesheet is
+   loaded. Kept for projects that themed the grid before the shared variables existed.
+4. **The built-in default** — a `light-dark()` pair, so it follows the page's
+   colour scheme.
+
+```css
+.in-root { --in-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa))); }
+```
+
+### The shared variables
+
+Defaults written light / dark.
+
+**Surfaces and text:** `--gbs-bg` (`#ffffff`/`#0b0b0e`), `--gbs-fg`
+(`#18181b`/`#f4f4f5`), `--gbs-muted` (`#71717a`/`#a1a1aa`), `--gbs-subtle`
+(`#f4f4f5`/`#1c1c20`), `--gbs-hover` (`#f4f4f5`/`#1f1f23`), `--gbs-input-bg`
+(`#ffffff`/`#121216`), `--gbs-readonly-bg` (`#fafafa`/`#0e0e12`),
+`--gbs-header-bg` (`#fafafa`/`#111114`), `--gbs-header-fg` (`#3f3f46`/`#d4d4d8`).
+
+**Borders and shape:** `--gbs-border` (`#e4e4e7`/`#27272a`),
+`--gbs-border-subtle` (`#f0f0f2`/`#1c1c20`), `--gbs-border-control`
+(`#a1a1aa`/`#52525b`), `--gbs-radius` (`8px`), `--gbs-font-size` (`13px`),
+`--gbs-shadow`, `--gbs-backdrop`.
+
+**Accent and status:** `--gbs-accent`, `--gbs-accent-soft`,
+`--gbs-accent-strong`, `--gbs-accent-fg`, `--gbs-focus`, `--gbs-danger`,
+`--gbs-danger-fg`, `--gbs-success`, `--gbs-warning`, `--gbs-info`.
+
+**Grid-specific:** `--gbs-row-alt`, `--gbs-row-hover`, `--gbs-row-selected`,
+`--gbs-row-selected-hover`, `--gbs-cell-px`, `--gbs-pin-shadow`,
+`--gbs-skeleton`, `--gbs-tab-fg`, `--gbs-tooltip-bg`, `--gbs-tooltip-fg`.
+
+### Per-component prefixes
+
+To change one component only, set its own prefix on its root class:
+
+| Component | Prefix | Root class |
+| --- | --- | --- |
+| DataGrid | `--dg-*` | `.dg-root` |
+| Combobox | `--cb-*` | `.cb-root` |
+| Toaster | `--ts-*` | `.ts-region` |
+| Input | `--in-*` | `.in-root` |
+| Button | `--bt-*` | `.bt-root` |
+
+```css
+.cb-root { --cb-accent: #7c3aed; --cb-radius: 12px; }
+```
+
+Toasts render on `<body>`, so grid/shared values they inherit must be set on
+`:root`.
+
+## 3. Slot classes
+
+`className` goes to the root element only. To reach an inner part, use
+`classNames`, a map of slot name to class string:
+
+```tsx
+<Input label="Email" classNames={{ root: "mb-4", label: "font-semibold", input: "font-mono" }} />
+```
+
+Slots are per component and listed in each `react/props.ts` and in this skill's
+`forms.md` / `overlays.md` / `data-display.md`. Passing a slot that does not
+exist is silently ignored, so check the list.
+
+Classes are joined with `cx` from `shared/core/cx.ts`, which drops falsy values
+— a conditional that evaluates to `undefined` contributes nothing.
+
+## 4. Tailwind
+
+Every `styles.css` declares:
+
+```css
+@layer theme, base, components, utilities;
+@layer components { /* the component's rules */ }
+```
+
+Component rules live in the `components` layer, so **Tailwind utilities passed
+through `className` / `classNames` win** without `!important`. That is the
+supported way to adjust spacing, typography and layout.
+
+```tsx
+<Button className="w-full sm:w-auto" classNames={{ content: "gap-3" }}>Save</Button>
+```
+
+Do not use `!important`, and do not write selectors against internal class names
+(`.bt-root`, `.dg-cell`) in app CSS — they are implementation detail. Use the
+variables or the slots.
+
+## 5. State attributes
+
+Components expose their state as `data-*` attributes, so you can style states
+without tracking them in React.
+
+| Attribute | Where |
+| --- | --- |
+| `data-state="open"` / `"closing"` | Combobox, Popover, Menu, Modal, toasts |
+| `data-side` | Popover, Menu, Tooltip — the side it settled on after flipping |
+| `data-size` | Controls that take a `size` |
+| `data-invalid`, `data-disabled` | Form controls |
+| `data-active`, `data-selected` | Combobox options, grid cells and rows |
+| `data-editing`, `data-pinned`, `data-density` | DataGrid |
+| `data-type`, `data-custom`, `data-swiping` | Toasts |
+| `data-position` | Toaster region |
+| `aria-sort` | DataGrid header cells |
+
+```css
+.cb-option[data-active] { outline: 2px solid var(--gbs-focus); }
+```
+
+## 6. Dark mode
+
+Colours are `light-dark()` pairs driven by the page's `color-scheme`, so the
+default is whatever the device prefers. To pin it, set `color-scheme` — the
+components follow:
+
+```css
+:root { color-scheme: light dark; }          /* follow the device */
+:root[data-theme="dark"] { color-scheme: dark; }
+:root[data-theme="light"] { color-scheme: light; }
+```
+
+The DataGrid additionally treats a `.dark` or `[data-theme="dark"]` ancestor as
+forcing a scheme.
+
+Do not maintain a second palette for dark mode. Override the `--gbs-*` variables
+with `light-dark()` pairs, or set them inside your own `[data-theme="dark"]`
+block, and every component follows.
+
+## 7. Right-to-left
+
+The components use logical properties and read `dir` from the document, so RTL
+works without configuration. Arrow keys in Menu, Switch and Tabs mirror
+automatically. The Toaster takes an explicit `dir` prop if one region needs to
+differ from the page.

package/.gbs/skills/gbs-components/references/toaster.md

@@ -0,0 +1,57 @@
+# Toaster and toast
+
+Notifications. `toast()` is callable from anywhere — components, event
+handlers, data layers, even outside React. No hook, context or provider.
+
+Mount `<Toaster />` **once**; call `toast()` from anywhere — components, event
+handlers, data layers, even outside React. No hook, context or provider.
+
+**Import from one path everywhere.** `toast()` and `<Toaster />` meet through a
+shared module-level store; two import paths can create two stores.
+
+```tsx
+// once, near the root
+import { Toaster } from "component-lib/toaster";
+<Toaster />
+
+// anywhere
+import { toast } from "component-lib/toaster";
+
+toast("Event created", { description: "Monday, 10:00" });
+toast.success("Saved");
+toast.error("Upload failed", { action: { label: "Retry", onClick: retry } });
+toast.warning("Storage almost full");
+toast.info("New version available");
+const id = toast.loading("Uploading…");     // stays until updated
+toast.update(id, { type: "success", title: "Uploaded" });
+toast.dismiss(id);                          // or toast.dismiss() for all
+
+toast.promise(saveUser(data), {
+  loading: "Saving…",
+  success: (user) => `${user.name} saved`,
+  error: (error) => `Could not save: ${(error as Error).message}`,
+});
+
+toast.custom(({ dismiss }) => <MyCard onClose={dismiss} />);
+```
+
+Every call returns the toast's id; reusing an on-screen id updates that toast.
+
+**Toast options:** `id`, `type` (`default` `success` `error` `warning` `info`
+`loading`), `description`, `duration` (5000; `0`/`Infinity` stays),
+`dismissible`, `action` / `cancel` (`{ label, onClick }`), `icon`, `className`,
+`render`, `onDismiss`, `onAutoClose`.
+
+**Toaster props:** `position` (`top-right`), `limit` (3), `duration` (5000),
+`closeButton` (true), `hotkey` (`["altKey","KeyT"]`), `icons`, `store`, `dir`,
+`className`, `classNames`, `style`, `localeText`.
+
+Slots: `region`, `list`, `toast`, `icon`, `content`, `title`, `description`,
+`actions`, `action`, `cancel`, `close`.
+
+Timers pause while the pointer is over the stack, while focus is inside it, and
+while the tab is hidden. The list is a polite live region; error toasts use
+`role="alert"`. **Alt+T** moves focus to the notifications.
+
+`toast()` does nothing during a server render — call it in the browser, e.g.
+after a Server Action resolves.

package/README.md

@@ -1,19 +1,46 @@
-# GBS Building Blocks 2.0 (v2.0.1)
-
-Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
-
-## Documentation
-
-For detailed documentation on usage and props, Please visit: [Building Block Documentation](https://gramprokit.vercel.app)
-
-## Beta Components
-
-New 2.0.0 beta (current version) is available for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app)
-
-## What's New 🎉 (Ver 2.0.1)
-
-- Update Candidate for next major change 2.0.0
-
-## Authors
-
-- [@anandhuremanan](https://www.github.com/anandhuremanan)
+# GBS Building Blocks 2.0 (v2.0.3)
+
+Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
+
+## Documentation
+
+For detailed documentation on usage and props, Please visit: [Building Block Documentation](https://gramprokit.vercel.app)
+
+## Beta Components
+
+New 2.0.0 beta (current version) is available for testing and feedback, Please visit: [Building Block Documentation v2.0.0 beta](https://gramprokit.vercel.app)
+
+## Agent skill
+
+Install the skill once per project so a coding agent uses these components
+correctly instead of guessing at the API:
+
+```bash
+npx gbs-add-block@latest -skill
+```
+
+It writes the skill at the root of the project you run it in, in the place each
+agent looks:
+
+| Agent | Gets |
+| --- | --- |
+| GBS SE Agent | `.gbs/skills/gbs-components/` (canonical) |
+| Claude Code | `.claude/skills/gbs-components/` |
+| Antigravity | `.agents/rules/gbs-components.md` |
+| Codex | a marked block in `AGENTS.md` |
+
+Pick a subset with `--for claude,codex`, or `--for none` for just `.gbs/`.
+Commit the result so everyone's agent picks it up. Re-run to update; a file you
+have edited is never replaced without `--force`.
+
+## What's New 🎉 (Ver 2.0.3)
+
+- Agent skill: stylesheets are now documented as a single import in the
+  project's global CSS. The previous wording showed the stylesheet import
+  beside the component import, which led coding agents to repeat it in every
+  component file they wrote — making CSS order depend on module import order,
+  and arriving late on lazy-loaded routes.
+
+## Authors
+
+- [@anandhuremanan](https://www.github.com/anandhuremanan)