@devalok/shilp-sutra 0.38.0 → 0.40.0

package/docs/components/ui/oauth-button.md

@@ -0,0 +1,86 @@
+# OAuthButton
+
+- Import: @devalok/shilp-sutra/ui/oauth-button
+- Server-safe: No
+- Category: ui
+
+## Exports
+- `OAuthButton` — primary brand-aware sign-in button
+- `OAuthGroup` — stacked layout wrapper with consistent spacing
+- `OAuthDivider` — `or`-style horizontal rule between OAuth row and email form
+- `OAuthConnectionRow` — settings-page row for a linked provider (Disconnect / Connect action)
+
+## OAuthButton props
+    provider: "google" | "apple" | "github" | "microsoft" | "x" | "linkedin" | "facebook" | "discord" | "slack" | "gitlab" | "sso" | "email" | "passkey" (required)
+    intent: "continue" | "signin" | "signup" (default "continue") — drives the verb in the label
+    appearance: "brand" | "outline" | "dark" (default "brand") — visual treatment
+    icon: ReactNode — override the default Tabler glyph with a brand-multicolour SVG
+    iconOnly: boolean — compact icon-only button; provider name preserved in aria-label
+    compact: boolean — short label ("Google" not "Continue with Google"); aria-label keeps long form
+    lastUsed: boolean — inline right-edge pill inside the button (a stronger pattern is reorder, below)
+    helperText: ReactNode — reassurance copy rendered below the button
+    children: ReactNode — override the default label entirely (i18n / custom copy)
+    size: inherited from Button ("xs" | "sm" | "md" | "lg" | compact + icon variants)
+    fullWidth, loading, onClick, onClickAsync, asyncFeedbackDuration, disabled — inherited from Button
+
+## Data attributes
+- `data-provider="<provider>"` — useful for analytics filtering
+- `data-oauth-appearance="<appearance>"`
+
+## OAuthGroup props
+    orientation: "vertical" | "horizontal" (default "vertical")
+    gap: "ds-02" | "ds-03" | "ds-04" (default "ds-03")
+    fullWidth: boolean (default true) — stretches children to fill width when vertical
+    reorderLastUsedFirst: boolean (default false) — pull the child with lastUsed to position 0
+        (Stripe-style — a stronger conversion lever than a visual badge alone)
+
+## OAuthDivider props
+    label: ReactNode (default "or")
+
+## OAuthConnectionRow props
+    provider: OAuthProvider (required)
+    connected: boolean (required)
+    accountLabel: ReactNode — account identifier shown next to the provider name (e.g. email)
+    onAction: (e) => void — synchronous click handler
+    onActionAsync: (e) => Promise<void> — uses Button's async state machine
+    actionLabel: ReactNode — override the "Disconnect" / "Connect <name>" copy
+    icon: ReactNode — override the default glyph
+    disabled: boolean
+
+## Defaults
+    intent="continue", appearance="brand", iconOnly=false, lastUsed=false
+
+## Example
+```jsx
+// Typical signup flow
+<OAuthGroup>
+  <OAuthButton provider="google" lastUsed />
+  <OAuthButton provider="apple" />
+  <OAuthButton provider="github" />
+</OAuthGroup>
+<OAuthDivider />
+<OAuthGroup>
+  <OAuthButton provider="passkey" appearance="outline" />
+  <OAuthButton provider="email" appearance="outline" />
+</OAuthGroup>
+
+// Async loading + success/error feedback
+<OAuthButton provider="google" fullWidth onClickAsync={signInWithGoogle} />
+
+// True brand-multicolour glyph from the provider's brand page
+<OAuthButton provider="google" icon={<GoogleGSvg />} />
+
+// Settings page — linked state
+<OAuthConnectionRow
+  provider="google"
+  connected
+  accountLabel="namaskar@devalok.in"
+  onAction={disconnectGoogle}
+/>
+```
+
+## Composability
+- **Built on Button.** Async state machine, loading/processing, sizes, and `fullWidth` are inherited. `variant` and `color` are managed internally — pass `appearance` instead.
+- **Tabler peer dep.** Default glyphs come from `@tabler/icons-react`. To match a provider's official multicolour mark, pass `icon={<YourSvg />}`.
+- **Brand-colour backgrounds.** `appearance="brand"` uses each provider's published button colour. `appearance="outline"` falls back to DS-neutral. `appearance="dark"` unifies every provider into an Apple-style black-on-white (light) / white-on-black (dark) treatment — useful when you want a row to feel visually consistent across providers.
+- **Last-used hint.** Storage is the consumer's responsibility — pass `lastUsed={user.lastProvider === 'google'}`.

package/docs/recipes/customize-brand.md

@@ -2,6 +2,21 @@
 
 Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
 
+## The fast path: use the Themer
+
+Before hand-writing variables, try **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)**. It is one funnel with four entry doors:
+
+- **Pick an archetype** — Linear, Stripe, Apple, Material, Notion, Vercel, or Devalok. Click → result page.
+- **Use my brand color** — paste a hex or dial OKLCH. Auto-generates the 12-step ramp and suggests an archetype.
+- **Walk me through it** — five-question wizard composes the answers into a theme.
+- **Just exploring** — land on a sample result page to see what you ship away with.
+
+Every door drops you at the same result screen: a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp), install commands for your package manager, and a share URL that encodes the theme.
+
+Paste the snippet into your global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's the whole flow — no `tailwind.config.ts`, no theme provider, no JS bundle.
+
+The rest of this doc covers what to do if the Themer doesn't expose a token you need to override (font stack, spacing scale, focus ring) — fall through to the hand-written cases below.
+
 ## How tokens layer
 
 Shilp Sutra's tokens are organized in three tiers:
@@ -56,19 +71,100 @@ To swap to teal:
 
 For a quick swap without redoing the full scale, only override step 9 (background) and step 11 (foreground). Other steps will still reference the original chroma — visually mismatched but functional.
 
-### Change the radius scale
+### Shape presets (`[data-shape]`)
+
+The simplest way to change roundness for the whole UI is to set a `data-shape` attribute on the document (or any subtree). Three presets ship by default — `sharp`, `slightly-rounded` (the default if no attribute), and `rounded`. Pill shapes (Badge, Switch, Slider, Avatar circle) stay pill in every preset.
+
+```html
+<!-- Whole-app, sharp/technical feel -->
+<html data-shape="sharp">
+
+<!-- Whole-app, soft/consumer feel -->
+<html data-shape="rounded">
+```
+
+You can scope it to a subtree if a particular section wants different shape language than the rest:
+
+```tsx
+<div data-shape="sharp">
+  <DeveloperConsole />
+</div>
+```
+
+Visual feel:
+
+| Preset | Identity | Comparable to |
+|---|---|---|
+| `sharp` | Technical, precise, "serious software" | Vercel, Linear, terminal UIs |
+| `slightly-rounded` (default) | Modern SaaS neutral | shadcn default, Stripe, Notion sidebar |
+| `rounded` | Friendly, soft, consumer | iOS, Notion content, modern startup landings |
+
+### Custom radius — override a role token
+
+If a preset doesn't fit, you can override any semantic radius role token directly. Components reference these role tokens (not the primitive scale), so a single override propagates everywhere.
+
+```css
+/* Tighten controls only; leave overlays / surfaces alone */
+:root {
+  --radius-control: 4px;
+}
+
+/* Or scoped to a subtree */
+.checkout {
+  --radius-control: 8px;
+  --radius-surface: 20px;
+}
+```
+
+The role tokens (defaults shown — the "slightly-rounded" preset):
+
+| Token                    | Default | Used by |
+|--------------------------|---------|---------|
+| `--radius-control`       | 6px     | Button, Input, Select, Tabs trigger, Toggle, Code block |
+| `--radius-control-inner` | 2px     | Checkbox box, ±/close buttons, inline Code |
+| `--radius-surface`       | 10px    | Card, Alert, Accordion |
+| `--radius-overlay-sm`    | 6px     | Tooltip, Toast |
+| `--radius-overlay`       | 10px    | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, listboxes |
+| `--radius-overlay-lg`    | 16px    | Dialog, AlertDialog, Sheet, BottomSheet, ColorInput picker |
+| `--radius-pill`          | 9999px  | Badge, StatusDot, Radio, Switch, Slider, Progress, Avatar circle |
+| `--radius-bubble`        | 24px    | ChatMessage bubble |
+
+### Build your own preset
+
+Define your own `[data-shape="…"]` block and swap to it whenever you want:
+
+```css
+[data-shape="brand-soft"] {
+  --radius-control:        8px;
+  --radius-control-inner:  3px;
+  --radius-surface:        14px;
+  --radius-overlay-sm:     8px;
+  --radius-overlay:        14px;
+  --radius-overlay-lg:     20px;
+  --radius-pill:           9999px;
+  --radius-bubble:         28px;
+}
+```
+
+```html
+<html data-shape="brand-soft">
+```
+
+### Change the primitive radius scale (advanced)
+
+If you're rebuilding the entire system rather than just rebranding, you can also override the primitive scale that the role tokens reference:
 
 ```css
 @theme {
-  --radius-ds-sm: 0.25rem;   /* small */
-  --radius-ds-md: 0.5rem;    /* default */
+  --radius-ds-sm: 0.25rem;
+  --radius-ds-md: 0.5rem;
   --radius-ds-lg: 0.75rem;
   --radius-ds-xl: 1rem;
   --radius: 0.5rem;          /* unsuffixed — generates bare `rounded` */
 }
 ```
 
-For a flat, sharp brand, set everything to `0`. For a heavily rounded brand, scale up.
+Most consumers should NOT touch this — overriding the role tokens above is the cleaner path.
 
 ### Change fonts
 

package/docs/recipes/index.md

@@ -29,9 +29,13 @@ If the framework is not listed, start with [install-vite.md](./install-vite.md)
 
 | Recipe | What it covers |
 |---|---|
-| [customize-brand.md](./customize-brand.md) | Token override cookbook — change colors, radius, fonts, spacing scale, dark-mode mapping |
+| [customize-brand.md](./customize-brand.md) | Token override cookbook — colors, radius role tokens, `[data-shape]` presets, fonts, spacing scale, dark-mode mapping. **Start here**, or skip ahead to the Themer ↓ |
 | [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
 
+### The fast path: Themer
+
+Don't want to write CSS variables by hand? Use **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)** — one funnel, four doors (pick an archetype, paste your brand color, take a wizard, or just explore). Every door drops you at a result page with a CSS snippet to paste, install commands, and a share URL.
+
 ## Diagnostics
 
 | Recipe | What it covers |

package/docs/recipes/install-astro.md

@@ -29,6 +29,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Astro's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `astro.config`
 
 Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):

package/docs/recipes/install-next-app-router.md

@@ -8,10 +8,9 @@ You are in this recipe if **all** of these are true:
 
 - `package.json` lists `"next"` at version `^13.0.0` or higher
 - An `app/` directory exists at the project root or under `src/`
-- An `app/layout.tsx` (or `.jsx`) file exists
-- No `pages/` directory at the project root, OR `pages/` exists but only contains `_app.{js,tsx}` and `_document.{js,tsx}` (legacy artifacts)
+- An `app/layout.{tsx,jsx}` file exists
 
-If `pages/` is the primary router, use [install-next-pages.md](./install-next-pages.md).
+If a `pages/` directory exists at the project root AND contains route files (not just `_app`/`_document` legacy artifacts from older `create-next-app` versions), use [install-next-pages.md](./install-next-pages.md). `create-next-app@16+` no longer scaffolds `pages/` for App Router projects.
 
 ## 2. Install dependencies
 
@@ -47,6 +46,23 @@ Add brand assets package if you need Devalok or Karm logos:
 pnpm add @devalok/shilp-sutra-brand
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*` (BarChart, LineChart, …)| `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` use with Tabler icons            | `pnpm add @tabler/icons-react`                                                                          |
+
+> These aren't in core deps so consumers who never render a chart, OTP input, or rich-text editor don't pay the install / bundle cost. One-time decision at install.
+
 ## 3. Configure PostCSS
 
 Create or update `postcss.config.mjs` at the project root:
@@ -211,8 +227,8 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   }
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
-- **Server Component imports.** Use per-component imports (`@devalok/shilp-sutra/ui/text`) inside Server Components. The barrel import `@devalok/shilp-sutra/ui` pulls client-only code and breaks RSC. See [server-components.md](./server-components.md).
-- **`p-3` vs `p-ds-03`.** Our spacing namespace is `--spacing-ds-*` to avoid collision with consumer numeric spacing. Use `p-ds-04`, not `p-4`.
+- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/docs/recipes/install-next-pages.md

@@ -16,6 +16,8 @@ If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install
 
 Same dependencies as the App Router recipe — see [install-next-app-router.md § 2](./install-next-app-router.md#2-install-dependencies). Replace `next-themes`'s `attribute="class"` setup with the same on Pages Router (it works identically).
 
+**Optional peer dependencies** — if you'll render `<DataTable>`, any chart, `<DatePicker>`, `<RichTextEditor>`, `<InputOTP>`, `<FilePreview>`, `<MarkdownViewer>`, or use Tabler icons, install the matching peers BEFORE first import. Full table at [install-next-app-router.md § 2a](./install-next-app-router.md#2a-optional-peer-dependencies-install-only-when-importing-the-matching-subpath) — identical for Pages Router.
+
 ## 3. PostCSS
 
 Same as App Router — see [§ 3](./install-next-app-router.md#3-configure-postcss).

package/docs/recipes/install-remix.md

@@ -25,6 +25,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Remix's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 ```ts

package/docs/recipes/install-tanstack-start.md

@@ -23,6 +23,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or the TanStack Start dev/build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `app.config.ts`
 
 ```ts

package/docs/recipes/install-vite.md

@@ -40,6 +40,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or `vite dev` / `vite build` will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 Use the official Tailwind 4 Vite plugin (faster than PostCSS for Vite):

package/docs/recipes/troubleshoot.md

@@ -97,6 +97,28 @@ transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
 
 If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
 
+## Symptom: Build error `Cannot find module 'sonner' / 'input-otp' / 'date-fns' / '@tiptap/react' / 'react-pdf' / 'react-markdown' / '@emoji-mart/react'`
+
+**Diagnosis:** an optional peer dependency is missing. Each component below has a peer it pulls only when imported. Install the matching peer (always BEFORE the first import):
+
+| You imported (per-component subpath) | Install                                                                                       |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|
+| `…/ui/toaster` or `…/ui/toast`       | `pnpm add sonner`                                                                             |
+| `…/ui/input-otp`                     | `pnpm add input-otp`                                                                          |
+| `…/composed/date-picker`             | `pnpm add date-fns`                                                                           |
+| `…/composed/emoji-picker`            | `pnpm add @emoji-mart/data @emoji-mart/react`                                                 |
+| `…/composed/extensions/emoji-node` or `…/extensions/emoji-suggestion` | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-text-editor`        | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-chat-input`         | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/file-preview`            | `pnpm add react-pdf react-zoom-pan-pinch`                                                     |
+| `…/composed/markdown-viewer`         | `pnpm add react-markdown react-syntax-highlighter remark-gfm`                                 |
+| `…/ai/block-renderer`, `…/ai/blocks/text`, `…/ai/blocks/error` | `pnpm add react-markdown remark-gfm`                                                          |
+| Any `…/ui/charts/*`                  | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+
+These ship as **optional** peers so consumers who never render the matching component don't pay the install cost. Once you import the component, the peer becomes required. Each affected component's JSDoc carries the same install hint — hover the import in your editor to see it inline.
+
+For the full table in your framework's install recipe, see `install-<framework>.md → §2a. Optional peer dependencies`.
+
 ## Symptom: Hydration warning on every page load (Next.js)
 
 **Diagnosis:** `next-themes` writes the `class` attribute on `<html>` before React hydrates, causing a server/client class mismatch.

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.38.0
+> Version: 0.40.0
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a
@@ -67,7 +67,8 @@ transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
 | `--leading-ds-*` | `leading-ds-tight`, `leading-ds-normal` | ds-namespaced |
 | `--tracking-*` | `tracking-tight`, `tracking-normal` | standard TW namespace |
 | `--font-*`, `--font-weight-*` | `font-sans`, `font-semibold` | standard TW namespace |
-| `--radius`, `--radius-ds-*` | `rounded` (bare), `rounded-ds-lg` | unprefixed + ds-namespaced |
+| `--radius`, `--radius-ds-*` | `rounded` (bare), `rounded-ds-lg` | unprefixed + ds-namespaced primitive scale |
+| `--radius-control`, `--radius-surface`, `--radius-overlay-*`, `--radius-pill`, `--radius-bubble` | `rounded-control`, `rounded-surface`, `rounded-overlay`, `rounded-pill`, `rounded-bubble` | semantic roles (PUBLIC) — components reference these, `[data-shape]` presets remap them |
 | `--shadow-*` | `shadow-raised`, `shadow-overlay` | semantic names only; bare `shadow` is NOT generated (TW4 has no default scale and we don't define `--shadow`) |
 | `--ease-*` | `ease-productive-standard` | semantic names |
 | `--breakpoint-*` | `md:`, `lg:` | standard TW namespace |
@@ -105,6 +106,94 @@ See `MIGRATION.md#v0370--tailwind-4-css-first-migration` (root of this package).
 
 ---
 
+## Shape Presets & Radius Roles (v0.39+)
+
+Radius has TWO layers:
+
+1. **Primitive scale** — `--radius-ds-sm/md/lg/xl/2xl/full` (private; internal building blocks).
+2. **Semantic roles** — `--radius-control`, `--radius-control-inner`, `--radius-surface`, `--radius-overlay-sm/md/lg`, `--radius-pill`, `--radius-bubble`. Components reference roles. Consumers customize these.
+
+### Role token reference
+
+| Token                    | Default (px) | Utility class            | Used by |
+|--------------------------|--------------|--------------------------|---------|
+| `--radius-control`       | 6            | `rounded-control`        | Button, Input, Select, Combobox, Autocomplete, NumberInput, Toggle, ToggleGroup, Tabs trigger (contained), menu items, sidebar menu button, stepper, pagination, code block, InputOTP slot |
+| `--radius-control-inner` | 2            | `rounded-control-inner`  | Checkbox box, +/− buttons, close X buttons, focus rings on text links, small badges, color preset swatches, skeleton text bars, inline Code |
+| `--radius-surface`       | 10           | `rounded-surface`        | Card, StatCard, DataTableCard, Alert, Accordion trigger, FileUpload dropzone, Tabs list (contained) |
+| `--radius-overlay-sm`    | 6            | `rounded-overlay-sm`     | Tooltip, Toast, charts internal tooltip |
+| `--radius-overlay`       | 10           | `rounded-overlay`        | Popover, HoverCard, DropdownMenu / ContextMenu / Menubar content, Select / Combobox / Autocomplete listbox, NavigationMenu viewport, DataTable bulk-actions toolbar, SplitButton dropdown |
+| `--radius-overlay-lg`    | 16           | `rounded-overlay-lg`     | Dialog, AlertDialog, Sheet (top corners), BottomSheet, ColorInput picker panel, ChatMessageInput wrapper, Sidebar inset variant |
+| `--radius-pill`          | 9999         | `rounded-pill`           | Badge, BadgeIndicator, StatusDot, Radio, Switch, Slider, Progress, Avatar circle, SegmentedControl item, ChatMessage reaction button, drag handles |
+| `--radius-bubble`        | 24           | `rounded-bubble`         | ChatMessage bubble |
+
+Bare `rounded-ds-*` and `rounded-full` are BANNED in components (enforced by pre-publish audit gate). Token-showcase stories (`forced-colors.stories.tsx`, `FoundationsShowcase.tsx`) are explicitly allowlisted.
+
+### Shape presets — `[data-shape]`
+
+Apply to `<html>`, app root, or any subtree. Three presets ship by default:
+
+| Preset | control / control-inner | surface | overlay-sm / overlay / overlay-lg | bubble | Feel |
+|---|---|---|---|---|---|
+| `sharp`              | 2 / 0   | 4   | 2 / 4 / 6     | 8  | Vercel / Linear / dev-tool |
+| `slightly-rounded` (default) | 6 / 2   | 10  | 6 / 10 / 16   | 24 | shadcn / Stripe / Notion sidebar |
+| `rounded`            | 10 / 4  | 16  | 10 / 16 / 24  | 32 | iOS / Notion content / consumer |
+
+```html
+<!-- Whole-app preset -->
+<html data-shape="sharp">
+
+<!-- Or scoped per subtree -->
+<div data-shape="rounded">...</div>
+```
+
+`--radius-pill` stays `9999px` in every preset by design — pill shapes are shape-by-meaning, not shape-by-style.
+
+### Per-token consumer overrides
+
+Override any role globally or scoped:
+
+```css
+:root { --radius-control: 4px; }                                /* tighten controls only */
+.checkout { --radius-control: 8px; --radius-surface: 20px; }    /* per-subtree */
+[data-shape="rounded"] .admin { --radius-control: 6px; }        /* extend a preset */
+```
+
+### Custom preset
+
+```css
+[data-shape="brand-soft"] {
+  --radius-control:        8px;
+  --radius-control-inner:  3px;
+  --radius-surface:        14px;
+  --radius-overlay-sm:     8px;
+  --radius-overlay:        14px;
+  --radius-overlay-lg:     20px;
+  --radius-pill:           9999px;
+  --radius-bubble:         28px;
+}
+```
+
+```html
+<html data-shape="brand-soft">
+```
+
+### Migration from `rounded-ds-*` / `rounded-full`
+
+```diff
+- className="rounded-ds-md ..."     → + className="rounded-control ..."
+- className="rounded-ds-lg ..."     → + className="rounded-surface ..."   /* card/panel context */
+- className="rounded-ds-lg ..."     → + className="rounded-overlay ..."   /* popover/dropdown context */
+- className="rounded-ds-xl ..."     → + className="rounded-overlay-lg ..."  /* dialog/sheet */
+- className="rounded-ds-2xl ..."    → + className="rounded-bubble ..."
+- className="rounded-ds-sm ..."     → + className="rounded-control-inner ..."
+- className="rounded-ds-full ..."   → + className="rounded-pill ..."
+- className="rounded-full ..."      → + className="rounded-pill ..."
+```
+
+Re-runnable codemod: `scripts/migrate-radius-roles.mjs` (dry-run by default, `--write` to apply).
+
+---
+
 ## Architecture Notes
 
 ### The Two-Axis Variant System
@@ -2943,6 +3032,92 @@ const { size, stroke } = useIconContext()
 
 ### v0.1.0
 - **Added** Initial release
+# OAuthButton
+
+- Import: @devalok/shilp-sutra/ui/oauth-button
+- Server-safe: No
+- Category: ui
+
+## Exports
+- `OAuthButton` — primary brand-aware sign-in button
+- `OAuthGroup` — stacked layout wrapper with consistent spacing
+- `OAuthDivider` — `or`-style horizontal rule between OAuth row and email form
+- `OAuthConnectionRow` — settings-page row for a linked provider (Disconnect / Connect action)
+
+## OAuthButton props
+    provider: "google" | "apple" | "github" | "microsoft" | "x" | "linkedin" | "facebook" | "discord" | "slack" | "gitlab" | "sso" | "email" | "passkey" (required)
+    intent: "continue" | "signin" | "signup" (default "continue") — drives the verb in the label
+    appearance: "brand" | "outline" | "dark" (default "brand") — visual treatment
+    icon: ReactNode — override the default Tabler glyph with a brand-multicolour SVG
+    iconOnly: boolean — compact icon-only button; provider name preserved in aria-label
+    compact: boolean — short label ("Google" not "Continue with Google"); aria-label keeps long form
+    lastUsed: boolean — inline right-edge pill inside the button (a stronger pattern is reorder, below)
+    helperText: ReactNode — reassurance copy rendered below the button
+    children: ReactNode — override the default label entirely (i18n / custom copy)
+    size: inherited from Button ("xs" | "sm" | "md" | "lg" | compact + icon variants)
+    fullWidth, loading, onClick, onClickAsync, asyncFeedbackDuration, disabled — inherited from Button
+
+## Data attributes
+- `data-provider="<provider>"` — useful for analytics filtering
+- `data-oauth-appearance="<appearance>"`
+
+## OAuthGroup props
+    orientation: "vertical" | "horizontal" (default "vertical")
+    gap: "ds-02" | "ds-03" | "ds-04" (default "ds-03")
+    fullWidth: boolean (default true) — stretches children to fill width when vertical
+    reorderLastUsedFirst: boolean (default false) — pull the child with lastUsed to position 0
+        (Stripe-style — a stronger conversion lever than a visual badge alone)
+
+## OAuthDivider props
+    label: ReactNode (default "or")
+
+## OAuthConnectionRow props
+    provider: OAuthProvider (required)
+    connected: boolean (required)
+    accountLabel: ReactNode — account identifier shown next to the provider name (e.g. email)
+    onAction: (e) => void — synchronous click handler
+    onActionAsync: (e) => Promise<void> — uses Button's async state machine
+    actionLabel: ReactNode — override the "Disconnect" / "Connect <name>" copy
+    icon: ReactNode — override the default glyph
+    disabled: boolean
+
+## Defaults
+    intent="continue", appearance="brand", iconOnly=false, lastUsed=false
+
+## Example
+```jsx
+// Typical signup flow
+<OAuthGroup>
+  <OAuthButton provider="google" lastUsed />
+  <OAuthButton provider="apple" />
+  <OAuthButton provider="github" />
+</OAuthGroup>
+<OAuthDivider />
+<OAuthGroup>
+  <OAuthButton provider="passkey" appearance="outline" />
+  <OAuthButton provider="email" appearance="outline" />
+</OAuthGroup>
+
+// Async loading + success/error feedback
+<OAuthButton provider="google" fullWidth onClickAsync={signInWithGoogle} />
+
+// True brand-multicolour glyph from the provider's brand page
+<OAuthButton provider="google" icon={<GoogleGSvg />} />
+
+// Settings page — linked state
+<OAuthConnectionRow
+  provider="google"
+  connected
+  accountLabel="namaskar@devalok.in"
+  onAction={disconnectGoogle}
+/>
+```
+
+## Composability
+- **Built on Button.** Async state machine, loading/processing, sizes, and `fullWidth` are inherited. `variant` and `color` are managed internally — pass `appearance` instead.
+- **Tabler peer dep.** Default glyphs come from `@tabler/icons-react`. To match a provider's official multicolour mark, pass `icon={<YourSvg />}`.
+- **Brand-colour backgrounds.** `appearance="brand"` uses each provider's published button colour. `appearance="outline"` falls back to DS-neutral. `appearance="dark"` unifies every provider into an Apple-style black-on-white (light) / white-on-black (dark) treatment — useful when you want a row to feel visually consistent across providers.
+- **Last-used hint.** Storage is the consumer's responsibility — pass `lastUsed={user.lastProvider === 'google'}`.
 # Pagination
 
 - Import: @devalok/shilp-sutra/ui/pagination