@tc96/parttens

React patterns without business rules, installed as source on top of your COSS components

Overview

• Source, not a dependency: the CLI copies the pattern source into your workspace. You own it and change it as you like
• Built on COSS: patterns import Button, Menu, Popover and the rest from your project's own UI alias
• Themeable: tc96 ships no CSS, tokens or theme, only layout classes on top of your components
• No business rules: your app provides prepared data and handles events. Filtering, sorting, persistence and API calls stay with you
• Layered: imports only go down a layer (patterns → elements → ui → utils), checked by a boundaries script
• Tested: Storybook stories, bun tests, consumer install checks and a view benchmark

Installation

npx @tc96/parttens add collection-views properties

Before copying anything, the CLI type-checks the patterns against your own ui components. If they do not type-check, it stops with exit code 1, in a --dry-run too. Fix the diagnostics it prints, or pass --force to install anyway.

Quick Start:

import { CollectionViewOutlet, TextProperty } from '@acme/patterns'

How it works

• Your COSS components: if a COSS component is missing, it is installed through shadcn. If you already have it, yours is reused, customizations included
• Your aliases: imports are rewritten to the aliases in your root components.json
• Your files: existing files are kept. shadcn asks before overwriting anything

Requirements

• React 19, TypeScript and Tailwind CSS 4
• COSS set up with shadcn, with components.json at the monorepo root
• Node and npm to run the CLI. Bun is not required

Consumer structure

tc96 expects a layered design system, in the spirit of atomic design, configured by one components.json at the monorepo root:

components.json        aliases: ui, utils (elements, helpers and patterns default to siblings of ui)
packages/
  ui/                  atoms: COSS components
  elements/            components COSS does not have, such as Text and IconFrame
  helpers/             React-free functions, such as amount formatting and rich text helpers
  patterns/            organisms: tc96 patterns
apps/
  web/                 templates and pages

{
  "aliases": {
    "components": "@acme/ui",
    "ui": "@acme/ui",
    "utils": "@acme/ui/lib/utils",
    "elements": "@acme/elements",
    "helpers": "@acme/helpers",
    "patterns": "@acme/patterns"
  }
}

Imports only go down a layer: patterns can import elements, ui and utils, and elements can import ui and utils. Each alias also needs exact and wildcard entries in the root tsconfig paths.

Install with an AI agent

Paste this into your coding agent, replacing the pattern names:

Install the @tc96/parttens patterns `collection-views` and `properties` in this project.

1. Find the root `components.json`. It must define `aliases.ui` and `aliases.utils`. `aliases.elements`, `aliases.helpers` and `aliases.patterns` are optional and default to siblings of `ui` (`@acme/ui` gives `@acme/elements`). If the file is missing, stop and ask me; do not run `shadcn init --force`, which rewrites it.
2. For `ui`, `elements`, `helpers` and `patterns`, check that the root `tsconfig.json` `paths` has an exact entry and a wildcard entry (`"@acme/patterns/*": ["./packages/patterns/src/*"]`) and that each alias points to an existing workspace package. If something is missing, show me the change and wait for my approval before editing.
3. Preview first, from any directory inside the repo (the CLI searches upward for `components.json`; use `--cwd` to override):
   npx @tc96/parttens add collection-views properties --dry-run
   Read the output. If it lists files that already exist or a destination I did not expect, such as a legacy folder with the same name, stop and ask me. If it stops with "do not type-check against your components", report the diagnostics and wait; do not add `--force`.
4. Install:
   npx @tc96/parttens add collection-views properties
   Answer no to any shadcn prompt that would overwrite a file I own. If the repo blocks npx, use `bunx` or `pnpm dlx`.
5. Do not edit the installed files or the COSS components in `ui`. Import from the `patterns` alias (`import { CollectionViewOutlet } from '@acme/patterns'`).
6. Run the typecheck and lint scripts of the workspace that received the files, and report what was installed, where, and any errors.

Patterns

| Pattern | Contents | | --- | --- | | collection-views | List, Kanban, Data Grid and Calendar views, toolbar, pagination, selection | | properties | Text, Date, Select, Person and other property displays, plus property groups | | editable | Inline editing compound | | checklist | Controlled item creation, completion, renaming, ordering, deletion and progress | | record-dialog | RecordDialog for create and edit; the handler returns boolean \| Promise<boolean> and the pattern settles the dialog | | record-preview | RecordPreview, a right-side sheet that previews a record with header actions, a close button and an optional footer, and RecordPreviewAction, its icon action; open state and content belong to the consumer | | record-group | RecordGroup, a collapsible group of label and value rows with optional header actions and footer, RecordGroupRow, its row, and RecordGroupAction, an icon action for the header; collapse state is optional and rows belong to the consumer | | widgets | Dashboard widgets in four groups: finance (market share, asset stats, risk score, balance, budget, cash flow, transactions, invoices), productivity (task progress, upcoming event, project card, agenda, world clock), CRM (pipeline, deals, activity feed, contact card) and gamification (level, streak, achievements, quests, progress HUD and footer), plus shared metric, stat list, avatar stack, progress ring, metric pill and the IconFrame element | | rich-text-editor | Notion-style block editor on headless Plate: paragraphs, headings, quote, nested lists, five marks, floating toolbar, / menu and a separate editable title | | state-surface | StateSurface for empty, no-result, error, permission and not-found, and StateGuard, which mounts its children only when the state is data | | settings | SettingsSection, a divided card of settings with an optional title, and SettingsRow, a row with title, description, an optional startSlot and the control in endSlot; values and controls belong to the consumer |

Filter Builder and responsive layouts are out of scope for the first version.

Updating

There is no package to update. To compare your installed files with the current version, run:

npx @tc96/parttens add collection-views --diff

Then apply the changes you want by hand.