@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/features/auth/.complete-account-form.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 515c6325e9385034801b28180faa7bce -->
+A fully-controlled, presentational React form component used on Sign Up and Accept Invitation screens to collect account details (name + password), with optional SSO provider shortcuts.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `CompleteAccountForm` | React component | Main form component — renders SSO buttons, name/password fields, and action buttons |
+| `CompleteAccountFormProps` | Interface | Full prop contract for the form, including field values, change handlers, labels, and error state |
+
+**Internal behaviours:**
+- **Deferred error display** — `useDeferredError` delays validation messages until blur or after a typing pause, preventing premature error flashes
+- **Enter-key submission** — `handleKeyDown` triggers `onSubmit` on Enter across all fields when not disabled/loading
+- **SSO section** — rendered conditionally; shows `SsoProviderButtons` + a divider only when `ssoProviders` is non-empty
+- **Optional back action** — `onBack` renders a transparent "Back" button; omitting it inserts a spacer to keep the submit button right-aligned per design
+
+## Usage Example
+
+```typescript
+import { CompleteAccountForm } from './complete-account-form'
+
+function SignUpPage() {
+  const [fields, setFields] = useState({
+    firstName: '', lastName: '', password: '', confirmPassword: ''
+  })
+
+  return (
+    <CompleteAccountForm
+      {...fields}
+      onFirstNameChange={(v) => setFields(f => ({ ...f, firstName: v }))}
+      onLastNameChange={(v) => setFields(f => ({ ...f, lastName: v }))}
+      onPasswordChange={(v) => setFields(f => ({ ...f, password: v }))}
+      onConfirmPasswordChange={(v) => setFields(f => ({ ...f, confirmPassword: v }))}
+      onSubmit={handleSubmit}
+      onBack={() => router.push('/org')}
+      ssoProviders={['google', 'microsoft']}
+      onSsoClick={(provider) => handleSso(provider)}
+      errors={{ password: 'Must be at least 8 characters' }}
+      loading={isSubmitting}
+    />
+  )
+}
+```
+
+> **Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/complete-account-form.tsx)

package/src/components/features/auth/.create-organization-form.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 350f1108c023fd5344b6b3ccac5cf4de -->
+Presentational, fully-controlled form component for the "Create Organization" (Sign Up) step of the OpenFrame auth flow.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `CreateOrganizationForm` | React component | Main form component — owns no state; delegates all state, validation, and submission to the consumer |
+| `CreateOrganizationFormProps` | Interface | Complete props contract covering field values, change handlers, error/status messages, SSO options, and layout customization |
+
+## Key Behaviors
+
+- **Deferred validation** — field errors are surfaced via `useDeferredError`, delaying display until the user blurs or pauses typing, avoiding premature error messages
+- **Inline status messages** — `emailStatus` and `domainStatus` props provide non-error feedback (e.g., availability checks); `errors.*` always takes precedence
+- **Domain suffix adornment** — `domainSuffix` renders a fixed suffix inside the domain input (e.g., `.openframe.ai`)
+- **SSO alternatives** — when `ssoProviders` is supplied, an "or continue with" divider and `SsoProviderButtons` render below the primary submit; `ssoDisabled` gates them independently of the form fields
+- **Enter-key submission** — `handleKeyDown` fires `onSubmit` on `Enter` across all inputs
+
+## Usage Example
+
+```typescript
+import { CreateOrganizationForm } from './create-organization-form'
+import { useState } from 'react'
+
+export function SignUpPage() {
+  const [email, setEmail] = useState('')
+  const [orgName, setOrgName] = useState('')
+  const [domain, setDomain] = useState('')
+  const [agreed, setAgreed] = useState(false)
+
+  return (
+    <CreateOrganizationForm
+      email={email}
+      organizationName={orgName}
+      domain={domain}
+      agreedToTerms={agreed}
+      onEmailChange={setEmail}
+      onOrganizationNameChange={setOrgName}
+      onDomainChange={setDomain}
+      onAgreedToTermsChange={setAgreed}
+      onSubmit={() => console.log('submit')}
+      domainSuffix=".openframe.ai"
+      termsUrl="/terms"
+      privacyPolicyUrl="/privacy"
+      errors={{ email: 'Email already in use' }}
+      ssoProviders={[{ id: 'google', label: 'Google' }]}
+      onSsoClick={(p) => console.log('SSO:', p)}
+    />
+  )
+}
+```
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)

package/src/components/features/auth/.index.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 9be13fc095a8c03f2c0e5ac3aacf88b2 -->
+Central barrel export file for the authentication UI component library, re-exporting all auth-related components from their individual modules.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `auth-benefits-panel` | Panel displaying authentication benefits/features |
+| `auth-branding` | Branding elements for auth screens |
+| `auth-shell` | Layout shell/wrapper for standard auth flows |
+| `back-to-login-link` | Navigation link to return to the login screen |
+| `complete-account-form` | Form for completing account setup |
+| `create-organization-form` | Form for creating a new organization |
+| `invite-link-invalid-modal` | Modal shown when an invite link is invalid or expired |
+| `login-form` | Standard username/password login form |
+| `openframe-sso-login-form` | OpenFrame SSO-specific login form |
+| `openframe-sso-signup-form` | OpenFrame SSO-specific signup form |
+| `password-reset-form` | Form for initiating or completing password reset |
+| `sso-auth-shell` | Layout shell/wrapper for SSO auth flows |
+| `sso-providers` | List/selector of available SSO identity providers |
+| `terms-agreement-label` | Terms of service agreement label/checkbox component |
+
+## Usage Example
+
+```typescript
+// Import any auth component directly from the library root
+import {
+  LoginForm,
+  AuthShell,
+  SsoProviders,
+  PasswordResetForm,
+  CreateOrganizationForm,
+} from '@openframe-oss-lib/auth'
+
+// Use in your application
+function AuthPage() {
+  return (
+    <AuthShell>
+      <LoginForm onSubmit={handleLogin} />
+      <SsoProviders providers={['google', 'microsoft']} />
+    </AuthShell>
+  )
+}
+```
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/features/auth/.invite-link-invalid-modal.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 1c25aff7c7d85b2821c5214291ab5645 -->
+Modal component displayed when a user visits an expired or invalid invitation link, offering a single action to return to the login page.
+
+## Key Components
+
+### `InviteLinkInvalidModal`
+A full-screen overlay with a centered card (bottom-pinned on mobile, vertically centered on tablet and above) that communicates the invalid/expired invite state. Includes an `XmarkIcon` dismiss button (desktop/tablet only) and a primary action button, both of which call `onBackToLogin` by default.
+
+### `InviteLinkInvalidModalProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onBackToLogin` | `() => void` | — | **Required.** Called when the action button is clicked |
+| `onClose` | `() => void` | `onBackToLogin` | Called when the X button is clicked |
+| `title` | `string` | `'Invite link not valid'` | Card heading |
+| `description` | `string` | `'This invitation link has expired…'` | Body copy |
+| `backLabel` | `string` | `'Back to Login'` | Action button label |
+| `className` | `string` | — | Extra classes applied to the backdrop |
+
+## Usage Example
+
+```typescript
+import { InviteLinkInvalidModal } from './invite-link-invalid-modal'
+
+function InviteFlow() {
+  const router = useRouter()
+
+  return (
+    <InviteLinkInvalidModal
+      onBackToLogin={() => router.push('/login')}
+      onClose={() => router.push('/login')}
+      title="Invite Expired"
+      description="Ask your administrator to resend the invite."
+      backLabel="Go to Login"
+    />
+  )
+}
+```
+
+## Source
+
+[`invite-link-invalid-modal.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/invite-link-invalid-modal.tsx)

package/src/components/features/auth/.login-form.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 0fa484ab1ed074f8b4a406ffde6dd7d1 -->
+Presentational, controlled login form component for the OpenFrame authentication UI. It renders an email input and SSO provider buttons, delegating all state, validation, and tenant discovery logic to the consumer.
+
+## Key Components
+
+### `LoginForm`
+The primary export. A fully controlled React component that renders:
+- A header with "Login to OpenFrame" branding
+- An email `Input` field with deferred error display (shown on blur or after a typing pause via `useDeferredError`)
+- `SsoProviderButtons` rendered below the email field, independently gated via `ssoDisabled` / `ssoEnabledProviders`
+
+### `LoginFormProps`
+Interface defining the full API surface:
+- `email` / `onEmailChange` — controlled email field
+- `errors.email` / `emailStatus` — error and informational status messages (errors take precedence)
+- `ssoProviders` / `onSsoClick` — SSO provider list and click handler
+- `ssoDisabled` / `ssoEnabledProviders` — fine-grained SSO button gating (all vs. selective)
+- `ssoActionLabel` — verb prefix for provider buttons (default: `"Continue with"`)
+- `onSubmit` — triggered on Enter key press
+
+## Usage Example
+
+```typescript
+import { LoginForm } from './login-form'
+import type { AuthSsoProvider } from './sso-providers'
+
+const providers: AuthSsoProvider[] = ['google', 'microsoft']
+
+<LoginForm
+  email={email}
+  onEmailChange={setEmail}
+  onSubmit={handleSubmit}
+  errors={{ email: emailError }}
+  emailStatus={{ message: 'Tenant found', variant: 'success' }}
+  ssoProviders={providers}
+  onSsoClick={handleSsoLogin}
+  ssoDisabled={!isTenantDiscovered}
+  ssoEnabledProviders={enabledProviders}
+/>
+```
+
+> **Source:** [`auth/login-form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/auth/login-form.tsx)

package/src/components/features/auth/.openframe-sso-login-form.md

@@ -0,0 +1,46 @@
+<!-- source-hash: b13c3b296f47effe28af02d380530cd1 -->
+Controlled, presentational login form component for OpenFrame's SSO flow, rendering email/password fields with deferred validation and submit/forgot-password actions.
+
+## Key Components
+
+### `OpenFrameSsoLoginForm`
+A fully controlled React form component intended to be rendered inside `SsoAuthShell`. Manages no internal state — all field values, change handlers, and error messages are passed via props.
+
+### `OpenFrameSsoLoginFormProps`
+The component's prop interface, covering:
+- **Field control:** `email`, `password`, `onEmailChange`, `onPasswordChange`
+- **Actions:** `onSubmit`, `onForgotPassword`
+- **State flags:** `loading`, `disabled`, `submitDisabled`
+- **Validation:** `errors.email`, `errors.password` (deferred via `useDeferredError`)
+- **Copy overrides:** `title`, `subtitle`, labels, placeholders, and button text
+
+### `useDeferredError`
+Hook used internally to delay showing validation messages until the user blurs a field or pauses typing, reducing noise during active input.
+
+## Usage Example
+
+```typescript
+import { OpenFrameSsoLoginForm } from './openframe-sso-login-form'
+
+function LoginPage() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+
+  return (
+    <OpenFrameSsoLoginForm
+      email={email}
+      password={password}
+      onEmailChange={setEmail}
+      onPasswordChange={setPassword}
+      onSubmit={() => console.log('Submit', email, password)}
+      onForgotPassword={() => console.log('Forgot password')}
+      loading={false}
+      errors={{ email: 'Invalid email format' }}
+    />
+  )
+}
+```
+
+Enter triggers submission via `onKeyDown` on both inputs. The "Continue" button uses the `accent` variant; "Forgot Password?" uses `transparent`.
+
+**Source:** [`openframe-sso-login-form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/openframe-sso-login-form.tsx)

package/src/components/features/auth/.openframe-sso-signup-form.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 0b3d08fe5ca4c4df07d20043c247f66d -->
+Presentational, fully-controlled sign-up form for creating OpenFrame SSO credentials (email, first/last name, password, confirm password) with deferred field-level validation.
+
+## Key Components
+
+### `OpenFrameSsoSignUpForm`
+The sole export — a stateless React component that delegates all state management to the parent. Key behaviours:
+
+- **Deferred errors** — field validation messages are surfaced via `useDeferredError`, showing only on blur or after a typing pause to avoid premature error states.
+- **Enter-key submission** — any field's `keydown` event triggers `onSubmit` when the form is not disabled or loading.
+- **Read-only email** — the `emailReadOnly` prop locks the email field (e.g. when email was verified in a prior step).
+- **Loading / disabled states** — `loading` shows a spinner on the submit button; `disabled` or `loading` disables all fields simultaneously.
+
+### `OpenFrameSsoSignUpFormProps`
+Full TypeScript interface exposing controlled field values, change handlers, submission callbacks, per-field error strings, and display-copy overrides (`title`, `subtitle`, `emailLabel`, `submitLabel`, `forgotPasswordLabel`).
+
+## Usage Example
+
+```typescript
+import { OpenFrameSsoSignUpForm } from './openframe-sso-signup-form'
+
+function SignUpPage() {
+  const [email, setEmail] = useState('')
+  const [firstName, setFirstName] = useState('')
+  const [lastName, setLastName] = useState('')
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+
+  return (
+    <OpenFrameSsoSignUpForm
+      email={email}
+      firstName={firstName}
+      lastName={lastName}
+      password={password}
+      confirmPassword={confirmPassword}
+      onEmailChange={setEmail}
+      onFirstNameChange={setFirstName}
+      onLastNameChange={setLastName}
+      onPasswordChange={setPassword}
+      onConfirmPasswordChange={setConfirmPassword}
+      onSubmit={() => console.log('submit')}
+      onForgotPassword={() => console.log('forgot password')}
+      errors={{ email: 'Invalid email', confirmPassword: 'Passwords do not match' }}
+      emailReadOnly
+      loading={false}
+    />
+  )
+}
+```
+
+**Source:** [`openframe-sso-signup-form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/openframe-sso-signup-form.tsx)

package/src/components/features/auth/.password-reset-form.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 95a5b5a463952e8f081061622ff4d509 -->
+A controlled, presentational React form component for the password reset flow, rendering two password fields, Cancel/Reset actions, and an optional "Back to Login" link.
+
+## Key Components
+
+### `PasswordResetForm`
+The main exported component. Fully controlled — the consumer owns field state, validation logic, and submission handling.
+
+### `PasswordResetFormProps`
+TypeScript interface exposing:
+
+| Prop | Type | Description |
+|---|---|---|
+| `password` / `confirmPassword` | `string` | Controlled field values |
+| `onPasswordChange` / `onConfirmPasswordChange` | `(value: string) => void` | Field change handlers |
+| `onSubmit` | `() => void` | Primary submit action |
+| `onCancel` | `() => void` | Secondary cancel action |
+| `onBackToLogin` | `() => void` (optional) | Shown on tablet/mobile only; desktop uses shell footer |
+| `submitDisabled` | `boolean` | Disables submit without locking fields |
+| `loading` / `disabled` | `boolean` | Full form lockout states |
+| `errors` | `{ password?, confirmPassword? }` | Validation messages (deferred via `useDeferredError`) |
+
+All labels and placeholders are overridable via dedicated string props.
+
+### `useDeferredError`
+Hook used internally to delay validation message display until blur or a pause in typing, reducing noise during active input.
+
+## Usage Example
+
+```typescript
+import { PasswordResetForm } from './password-reset-form'
+import { useState } from 'react'
+
+function ResetPage() {
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+
+  const errors = {
+    confirmPassword:
+      password !== confirmPassword ? 'Passwords do not match' : undefined,
+  }
+
+  return (
+    <PasswordResetForm
+      password={password}
+      confirmPassword={confirmPassword}
+      onPasswordChange={setPassword}
+      onConfirmPasswordChange={setConfirmPassword}
+      onSubmit={() => console.log('Submitting reset')}
+      onCancel={() => console.log('Cancelled')}
+      onBackToLogin={() => console.log('Back to login')}
+      errors={errors}
+      submitDisabled={password !== confirmPassword}
+    />
+  )
+}
+```

package/src/components/features/auth/.sso-auth-shell.md

@@ -0,0 +1,35 @@
+<!-- source-hash: 42f6dac64028d99b3a2ea49a0c3914d5 -->
+Centered single-column layout shell for OpenFrame SSO (IdP) authentication screens, composing the wordmark, form content, and "Powered by Flamingo" branding into a full-height page structure.
+
+## Key Components
+
+- **`SsoAuthShell`** — Full-page wrapper component that arranges SSO login/sign-up screens with a top wordmark, centered form card (max-width 600px), and a compact footer branding element.
+- **`SsoAuthShellProps`** — Interface accepting `children` (the form card content) and an optional `className` for layout overrides.
+- **`OpenFrameWordmark`** — Branding element rendered at the top of the shell (imported from `auth-branding`).
+- **`PoweredByFlamingo`** — Compact footer branding element rendered at the bottom (imported from `auth-branding`).
+
+## Usage Example
+
+```typescript
+import { SsoAuthShell } from './sso-auth-shell'
+import { LoginForm } from './login-form'
+
+export default function SsoLoginPage() {
+  return (
+    <SsoAuthShell>
+      <LoginForm />
+    </SsoAuthShell>
+  )
+}
+```
+
+## Notes
+
+- Designed exclusively for SSO/IdP screens — no marketing or split-panel layout.
+- Uses design tokens (`--spacing-system-xl`, `bg-ods-bg`) for consistent spacing and background.
+- `cn` utility merges Tailwind classes, allowing consumers to override layout via `className`.
+- Marked `'use client'` — requires a React client boundary (Next.js App Router compatible).
+
+## Source
+
+[`sso-auth-shell.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/sso-auth-shell.tsx)

package/src/components/features/auth/.sso-providers.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 061672449705d5265894d8263494baea -->
+Renders a configurable stack of SSO provider buttons (`openframe`, `google`, `microsoft`) for use in authentication forms.
+
+## Key Components
+
+- **`AuthSsoProvider`** — Union type of supported SSO provider keys: `'openframe' | 'google' | 'microsoft'`
+- **`PROVIDER_META`** — Record mapping each provider to its display name and icon component; the `openframe` icon applies CSS variable-based theming
+- **`SsoProviderButtonsProps`** — Props interface for the button group component
+- **`SsoProviderButtons`** — Primary export; renders full-width, stacked `Button` elements for each requested provider
+
+## Usage Example
+
+```typescript
+import {
+  SsoProviderButtons,
+  type AuthSsoProvider,
+} from './sso-providers'
+
+function LoginForm() {
+  const handleSso = (provider: AuthSsoProvider) => {
+    console.log('Signing in with', provider)
+  }
+
+  return (
+    <SsoProviderButtons
+      providers={['openframe', 'google', 'microsoft']}
+      actionLabel="Sign in with"
+      onSsoClick={handleSso}
+      // Only enable providers the tenant actually supports
+      enabledProviders={['google']}
+    />
+  )
+}
+```
+
+## Notes
+
+- `actionLabel` (default `"Continue with"`) is prepended to provider names (e.g. `"Continue with Google"`), but is **ignored** for `openframe`, which always renders as `"OpenFrame SSO"`
+- `enabledProviders` selectively disables buttons not in the list — useful when tenant discovery determines which providers are available; the top-level `disabled` prop still takes precedence
+- Disabled buttons apply the `bg-ods-bg` class to visually recede to the page background, matching the design system's disabled input treatment
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/sso-providers.tsx)

package/src/components/features/auth/.terms-agreement-label.md

@@ -0,0 +1,28 @@
+<!-- source-hash: 05dd95b5ac235a47995911312e9065f8 -->
+Renders the "Agree to Terms & Privacy Policy by signing up." label used alongside signup checkboxes, with configurable links for the Terms and Privacy Policy URLs.
+
+## Key Components
+
+- **`TermsAgreementLabelProps`** — Interface accepting optional `termsUrl` and `privacyPolicyUrl` strings (both default to `'#'`)
+- **`TermsAgreementLabel`** — Client component that renders a `<span>` with inline anchor tags for Terms and Privacy Policy; links open in a new tab and stop click propagation to prevent unintended checkbox toggling
+
+## Usage Example
+
+```typescript
+import { TermsAgreementLabel } from './terms-agreement-label'
+
+// With custom URLs
+<TermsAgreementLabel
+  termsUrl="https://example.com/terms"
+  privacyPolicyUrl="https://example.com/privacy"
+/>
+
+// With defaults (links point to '#')
+<TermsAgreementLabel />
+```
+
+## Notes
+
+- `onClick` on each anchor calls `event.stopPropagation()` to prevent the parent checkbox `label` element from toggling when a link is clicked
+- Both links use `target="_blank"` with `rel="noopener noreferrer"` for secure external navigation
+- Styled with ODS design tokens (`text-ods-text-primary`, `text-ods-text-secondary`)

package/src/components/features/board/.board-column-header.md

@@ -1,38 +1,44 @@
-<!-- source-hash: 1ad6ce49d76bfa9f7bbe6737c01b2305 -->
-Renders the header for a Kanban board column, supporting both expanded and collapsed states with ticket status display, count, and optional ticket creation.
+<!-- source-hash: ca02054e0e467a0cfd1ca2c788a01f8f -->
+Renders the header for a single Kanban board column, handling both expanded and collapsed states with status tags, ticket counts, and optional action buttons.
 
 ## Key Components
 
 ### `BoardColumnHeaderProps`
+
 | Prop | Type | Description |
-|------|------|-------------|
-| `column` | `BoardColumnDef` | Column definition including id, label, color, and tickets |
-| `collapsed` | `boolean` | Controls collapsed/expanded display mode |
+|---|---|---|
+| `column` | `BoardColumnDef` | Column definition including label, tickets, status key, and optional color |
+| `collapsed` | `boolean` | Controls collapsed vs. expanded layout (default: `false`) |
 | `onToggleCollapse` | `() => void` | Callback to toggle column collapse state |
-| `onAddTicket` | `() => void` (optional) | Callback to trigger ticket creation |
+| `onAddTicket` | `() => void` | Optional callback to create a new ticket in this column |
+| `onArchive` | `() => void` | Optional callback to archive resolved tickets |
 
 ### `BoardColumnHeader`
-Client component that renders two distinct layouts:
-- **Collapsed:** Vertical layout with expand icon, rotated status tag, and ticket count
-- **Expanded:** Horizontal layout with status tag, count, collapse button, and optional add-ticket button
 
-Uses `getTicketStatusConfig` to determine whether to use a built-in status color or a custom column color for the `TicketStatusTag`.
+The main exported component. Renders two distinct layouts:
+
+- **Collapsed** — vertical layout with an expand arrow, rotated `TicketStatusTag`, and ticket count
+- **Expanded** — horizontal layout with the status tag, count, and action buttons (collapse, archive, add)
+
+**Status resolution logic:** Uses `resolveTicketStatus` to detect canonical statuses (`ACTIVE`, `RESOLVED`, etc.). Known statuses render with their built-in variant/icon; unrecognized IDs (e.g., custom UUID statuses) fall back to the column's `color` prop.
 
 ## Usage Example
 
 ```typescript
-import { BoardColumnHeader } from './board-column-header'
-
 <BoardColumnHeader
   column={{
-    id: 'in-progress',
-    label: 'In Progress',
-    color: '#FFC008',
-    tickets: [...],
+    id: 'open',
+    label: 'Open',
+    tickets: [],
     total: 12,
+    statusKey: 'ACTIVE',
+    color: undefined,
   }}
   collapsed={false}
   onToggleCollapse={() => setCollapsed(prev => !prev)}
-  onAddTicket={() => openCreateTicketModal('in-progress')}
+  onAddTicket={() => openNewTicketModal()}
+  onArchive={() => archiveResolvedTickets()}
 />
-```
+```
+
+**Source:** [`board-column-header.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/board-column-header.tsx)

package/src/components/features/board/.board-column.md

@@ -1,43 +1,43 @@
-<!-- source-hash: 1bf9b2d5d2d477b1115c900de71defaa -->
-Renders a single kanban board column with drag-and-drop support, collapsible layout, infinite scroll via IntersectionObserver, and ticket card rendering.
+<!-- source-hash: 410ed43f828981219aefe056be55cd69 -->
+A kanban-style board column component with drag-and-drop support, infinite scroll, collapse/expand behavior, and ticket card rendering.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `BoardColumn` | Component | Main column shell handling collapsed/expanded state, border joining, and color tinting |
-| `BoardColumnProps` | Interface | Public API for the column component |
-| `ColumnBody` | Internal Component | Scrollable droppable zone with `SortableContext`, infinite scroll sentinel, and loading states |
-| `SkeletonStack` | Internal Component | Renders `n` skeleton placeholders during initial load |
-| `EmptyState` | Internal Component | Illustrated empty state shown when a column has no tickets |
+### `BoardColumn` (exported)
+The primary column container. Renders a collapsible column with a header, divider, and body. Supports visual joining with adjacent columns via `joinLeft`/`joinRight` props and applies tinted background colors for non-system columns.
+
+### `ColumnBody` (internal)
+Handles the droppable zone (`@dnd-kit/core`), sortable ticket list (`@dnd-kit/sortable`), and infinite scroll via `IntersectionObserver`. Manages refs for both the scroll container and the droppable drop target.
+
+### `SkeletonStack` (internal)
+Renders a configurable number of `TicketCardSkeleton` placeholders during initial load.
+
+### `EmptyState` (internal)
+Displays a centered empty state with a tag icon when a column has no tickets.
+
+## Key Props (`BoardColumnProps`)
+
+| Prop | Type | Description |
+|---|---|---|
+| `column` | `BoardColumnDef` | Column definition including tickets, color, and state flags |
+| `collapsed` | `boolean` | Collapses column to `w-14` |
+| `onToggleCollapse` | `() => void` | Toggle handler |
+| `onLoadMore` | `(columnId: string) => void` | Triggered by intersection sentinel |
+| `joinLeft` / `joinRight` | `boolean` | Removes borders/radius for adjacent column groups |
+| `renderAssignSlot` | `(ticket: BoardTicket) => ReactNode` | Custom assignee slot renderer |
 
 ## Usage Example
 
 ```typescript
 <BoardColumn
-  column={{
-    id: 'open',
-    label: 'Open',
-    color: '#3B82F6',
-    tickets: myTickets,
-    hasMore: true,
-    isLoading: false,
-    isLoadingMore: false,
-  }}
+  column={column}
   collapsed={false}
-  onToggleCollapse={() => setCollapsed(c => !c)}
-  onAddTicket={(columnId) => openNewTicketModal(columnId)}
+  onToggleCollapse={() => setCollapsed(id, !collapsed)}
+  onAddTicket={(colId) => openNewTicketModal(colId)}
   getTicketHref={(ticketId) => `/tickets/${ticketId}`}
-  renderAssignSlot={(ticket) => <AssigneePicker ticket={ticket} />}
-  onLoadMore={(columnId) => fetchNextPage(columnId)}
-  joinLeft={false}
-  joinRight={true}
+  renderAssignSlot={(ticket) => <AvatarPicker ticket={ticket} />}
+  onApprove={(ticketId) => approveTicket(ticketId)}
+  onLoadMore={(colId) => fetchMoreTickets(colId)}
+  joinLeft
 />
-```
-
-## Notes
-
-- **Drag-and-drop**: Uses `@dnd-kit/core` (`useDroppable`) and `@dnd-kit/sortable` (`SortableContext`) — drop target is disabled when `column.dropDisabled` is set.
-- **Infinite scroll**: An `IntersectionObserver` watches a 1px sentinel div at the bottom of the scroll container; `onLoadMore` fires when it enters the viewport. Scroll is paused while `isLoadingMore` is true.
-- **Collapsed state**: When `collapsed=true`, the column shrinks to `w-14` and hides the body; the header remains visible.
-- **Joined borders**: `joinLeft`/`joinRight` props remove border radii and borders on adjacent edges for seamless multi-column layouts.
+```