@cdt5058/json-render-uswds 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# @cdt5058/json-render-uswds
+
+## 0.1.1
+
+### Patch Changes
+
+- 8aee03d: Fix install documentation and peer dependency declarations.
+
+  - Declare `@uswds/uswds` as an optional `peerDependency` so the existing `peerDependenciesMeta.optional` flag is no longer inert.
+  - Rewrite the README `Install` section to match reality: list the actual peers users must provide (`react`, `react-dom`, `@uswds/uswds`, `zod`), note the `Node.js >=22.14.0` and React 19 requirements, and clarify that `@json-render/core` / `@json-render/react` are pulled in as transitive runtime dependencies.
+
+## 0.1.0
+
+### Minor Changes
+
+- 7bccec6: ### Minor Changes
+
+  - **Initial public release** of @cdt5058/json-render-uswds - a U.S. Web Design System component library for @json-render/core
+  - **Component library** providing accessible, government-compliant React components that render from JSON specifications
+  - **Full USWDS integration** with support for common form elements, layouts, and UI patterns
+  - **Accessibility first** - all components follow WCAG 2.1 AA standards and USWDS accessibility guidelines
+  - **Type-safe** - full TypeScript support with comprehensive prop types
+  - **Dual exports** - ESM and CommonJS builds for maximum compatibility
+  - **Public readiness** - issue templates, contributing guidelines, and comprehensive documentation
+
+  ### What's Included
+
+  - Complete set of USWDS components (buttons, forms, navigation, step indicators, pagination, and more)
+  - Component catalog with schema definitions
+  - React integration with state binding and event handling
+  - Support for AI/LLM-generated UI specifications
+
+  This is the first stable release ready for production use.
+
+## 0.1.0
+
+### Initial Release
+
+First release of `@cdt5058/json-render-uswds` — a standalone U.S. Web Design System (USWDS) component library for `@json-render/core`.
+
+#### 58 USWDS Components
+
+**Layout (6):** Grid, CardGroup, Card, Divider, Footer, Section
+
+**Navigation (9):** Header, SkipNav, SideNav, LanguageSelector, Link, InPageNavigation, Breadcrumb, Identifier, GovBanner
+
+**Data Display (9):** Collection, IconList, Tooltip, Table, Heading, Text, Prose, Hero, GraphicList
+
+**Feedback (5):** Alert, SiteAlert, Tag, SummaryBox, ProcessList
+
+**Forms (20):** Button, ButtonGroup, Input, Textarea, Select, Checkbox, CheckboxGroup, Radio, FileInput, Search, RangeInput, DateInputGroup, DateRangePicker, InputMask, Password, ComboBox, DatePicker, TimePicker, CharacterCount, Form
+
+**Utilities (9):** Accordion, Pagination, StepIndicator, Icon, InputGroup, List, ValidationChecklist, EmbedContainer, Modal
+
+All components are WCAG 2.1 AA compliant with semantic HTML, ARIA attributes, and full keyboard navigation support.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 json-render contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,45 +1,211 @@
 # @cdt5058/json-render-uswds
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![CI](https://github.com/ctrimm/json-render-uswds/actions/workflows/ci.yml/badge.svg)](https://github.com/ctrimm/json-render-uswds/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@cdt5058/json-render-uswds)](https://www.npmjs.com/package/@cdt5058/json-render-uswds)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+U.S. Web Design System (USWDS) component library for [`@json-render/core`](https://github.com/vercel-labs/json-render). Generate accessible, government-compliant React UIs from JSON specs.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+> Built on top of [json-render](https://github.com/vercel-labs/json-render) by [Vercel](https://vercel.com) — the Generative UI framework for safe, schema-constrained AI-generated interfaces.
 
-## Purpose
+![Public Records Request page generated from a JSON spec](screenshots/preview.png)
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@cdt5058/json-render-uswds`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Demo
 
-## What is OIDC Trusted Publishing?
+A live demo app is included in [`examples/demo`](examples/demo). It lets you describe a page in plain English and generate a USWDS spec via AI, or load pre-built fixture pages instantly.
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```bash
+cd examples/demo
+npm install
+# Add your Anthropic API key to .env.local
+cp .env.example .env.local
+npm run dev
+```
 
-## Setup Instructions
+Then open [http://localhost:3000](http://localhost:3000).
 
-To properly configure OIDC trusted publishing for this package:
+## Install
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+**Prerequisites:** Node.js `>=22.14.0`, React `^19.0.0`, and `zod ^4.0.0`.
 
-## DO NOT USE THIS PACKAGE
+```bash
+npm install @cdt5058/json-render-uswds react react-dom @uswds/uswds zod
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+`@json-render/core` and `@json-render/react` are pulled in automatically as runtime dependencies — you do not need to install them yourself. `@uswds/uswds` is an optional peer (only needed if you want to import the CSS from the npm package rather than the CDN).
 
-## More Information
+## Import USWDS CSS
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```tsx
+import "@uswds/uswds/css/uswds.css";
+```
 
----
+Or via CDN:
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/uswds/3.8.2/css/uswds.min.css">
+```
 
-**Maintained for OIDC setup purposes only**
+## Quick Start
+
+### 1. Define your catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { uswdsComponentDefinitions } from "@cdt5058/json-render-uswds/catalog";
+
+const catalog = defineCatalog(schema, {
+  components: uswdsComponentDefinitions,
+});
+```
+
+### 2. Create a registry and render
+
+```tsx
+import { defineRegistry, Renderer } from "@json-render/react";
+import { uswdsComponents } from "@cdt5058/json-render-uswds";
+import type { Spec } from "@json-render/core";
+
+const { registry } = defineRegistry(catalog, {
+  components: uswdsComponents,
+});
+
+export function MyApp({ spec }: { spec: Spec }) {
+  return <Renderer spec={spec} registry={registry} />;
+}
+```
+
+### 3. Generate a system prompt for AI
+
+```typescript
+const systemPrompt = catalog.prompt();
+// Pass to your AI model — it will generate specs constrained to USWDS components
+```
+
+## Components
+
+58 USWDS components organized by category:
+
+### Layout
+`Grid` `CardGroup` `Card` `Divider` `Footer` `Section`
+
+### Navigation
+`Header` `SkipNav` `SideNav` `LanguageSelector` `Link` `InPageNavigation` `Breadcrumb` `Identifier` `GovBanner`
+
+### Data Display
+`Collection` `IconList` `Tooltip` `Table` `Heading` `Text` `Prose` `Hero` `GraphicList`
+
+### Feedback
+`Alert` `SiteAlert` `Tag` `SummaryBox` `ProcessList`
+
+### Forms
+`Button` `ButtonGroup` `Input` `Textarea` `Select` `Checkbox` `CheckboxGroup` `Radio` `FileInput` `Search` `RangeInput` `DateInputGroup` `DateRangePicker` `InputMask` `Password` `ComboBox` `DatePicker` `TimePicker` `CharacterCount` `Modal` `Form`
+
+### Utilities
+`Accordion` `Pagination` `StepIndicator` `Icon` `InputGroup` `List` `ValidationChecklist` `EmbedContainer`
+
+## Custom Components
+
+Extend the catalog with your own components alongside USWDS:
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { uswdsComponentDefinitions } from "@cdt5058/json-render-uswds/catalog";
+import { uswdsComponents } from "@cdt5058/json-render-uswds";
+import { defineRegistry } from "@json-render/react";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    ...uswdsComponentDefinitions,
+    AgencyBanner: {
+      props: z.object({
+        name: z.string(),
+        logoUrl: z.string().nullable(),
+      }),
+      description: "Custom agency-specific banner",
+    },
+  },
+});
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    ...uswdsComponents,
+    AgencyBanner: ({ props }) => (
+      <div className="usa-banner">
+        {props.logoUrl && <img src={props.logoUrl} alt={props.name} />}
+        <span>{props.name}</span>
+      </div>
+    ),
+  },
+});
+```
+
+## Accessibility
+
+All components are built to meet federal accessibility requirements:
+
+- **WCAG 2.1 AA** compliant
+- Semantic HTML with proper landmark regions
+- ARIA roles, labels, and live regions
+- Full keyboard navigation
+- Visible focus indicators
+- Color contrast ratios that meet federal standards
+- Accessible form validation and error messages
+
+See the [USWDS Accessibility guidance](https://designsystem.digital.gov/how-to-use-uswds/accessibility/) for more details.
+
+## State Management
+
+Use `StateProvider` from `@json-render/react` to enable data binding:
+
+```tsx
+import { StateProvider, createStateStore } from "@json-render/react";
+
+const store = createStateStore({ formData: {} });
+
+<StateProvider store={store}>
+  <Renderer spec={spec} registry={registry} />
+</StateProvider>
+```
+
+## AI-Assisted Development
+
+This repo includes a [Claude Code](https://claude.ai/code) skill at `skills/uswds/SKILL.md`. If you use Claude Code, the skill gives Claude context about all 58 USWDS components, installation, and usage patterns — so it can help you build USWDS specs and catalogs without needing to look things up.
+
+## Troubleshooting
+
+**`Cannot find module '@cdt5058/json-render-uswds'`**
+Make sure you've run `npm install` and that your bundler supports the `exports` field in `package.json` (Webpack 5+, Vite, Next.js 12+ all do).
+
+**USWDS styles aren't applying**
+You must import the USWDS CSS yourself — it is not bundled. Add one of:
+```tsx
+import "@uswds/uswds/css/uswds.css"; // via npm package
+```
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/uswds/3.8.2/css/uswds.min.css">
+```
+
+**TypeScript errors about `zod` types**
+Ensure you have `zod ^4.0.0` installed. Zod 3.x is not compatible.
+
+**Components render but look unstyled**
+Check that your bundler is processing CSS imports. In Next.js, import the CSS in `app/layout.tsx` or `pages/_app.tsx`. In Vite, import it in `main.tsx`.
+
+**Demo app fails to start**
+The demo requires API keys. Copy `.env.example` to `.env.local` and add at least `ANTHROPIC_API_KEY`. Local model support (Ollama) requires no API key — select a local model from the model picker.
+
+## Credits
+
+This package is a USWDS adapter built on top of **[json-render](https://github.com/vercel-labs/json-render)**, an open-source Generative UI framework created and maintained by [Vercel](https://vercel.com). The core rendering engine, catalog system, schema design, and React renderer are all their work.
+
+- [json-render on GitHub](https://github.com/vercel-labs/json-render)
+- [json-render documentation](https://json-render.dev)
+- [U.S. Web Design System](https://designsystem.digital.gov/)
+
+## License
+
+Apache-2.0