Merge remote-tracking branch 'origin/main' into codegen-bot/integrate-shadcn-input-group-1762992679

Author: jaruesink

.cursor/rules/versioning-with-npm.mdc

@@ -8,7 +8,7 @@ You are an expert release manager for a Yarn 4 monorepo who uses the npm CLI for
 - Treat new components and minor fixes as patch releases when they are additive and low-risk.
 - Reserve minor/major only for notable feature waves or breaking changes.
 
-Note: While the repo supports Changesets for broader release coordination, this rule documents the npm CLI flow for quick iterations.
+Note: The primary release workflow uses Changesets (`yarn changeset` → `yarn changeset version` → automatic CI/CD publish). This rule documents the npm CLI flow for quick iterations when bypassing changesets.
 
 ## What Counts As “Small”
 - Additive components (new UI or form wrappers) without breaking changes
@@ -47,7 +47,8 @@ Guidelines:
 
 ## Open PR and Merge
 - Push your branch and open a PR.
-- When the PR merges into `main`, GitHub CI publishes the package. No manual tagging or `npm publish` needed.
+- When the PR merges into `main`, GitHub CI automatically publishes the package using npm trusted publishers (OIDC). No manual tagging or `npm publish` needed, and no npm tokens required.
+- **Note:** The release workflow uses [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) for secure, tokenless publishing. Ensure the trusted publisher is configured on npmjs.com for the package.
 
 ## Minor / Major (When Needed)
 - Minor: larger feature sets or notable additions across multiple components

.github/workflows/release.yml

@@ -7,27 +7,56 @@ on:
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
+permissions:
+  id-token: write # Required for OIDC trusted publishing
+  contents: write # Required for pushing git tags after publishing
+
 jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-      - name: Setup Node.js 20.x
-        uses: actions/setup-node@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          # registry-url enables OIDC authentication for npm publish
+
+      - name: Install npm 11.5.1+ for trusted publishing
+        run: npm install -g npm@latest
+        # Trusted publishing requires npm CLI 11.5.1 or later
 
       - name: Enable Corepack
         run: corepack enable
 
       - name: Install Correct Yarn Version
-        run: corepack prepare yarn@4.4.1 --activate
+        run: corepack prepare yarn@4.9.1 --activate
 
       - name: Install Dependencies
-        run: yarn
+        run: yarn install --immutable
+
+      - name: Verify npm and OIDC setup
+        run: |
+          echo "npm version: $(npm --version)"
+          echo "Node version: $(node --version)"
+          # Check if we're in a GitHub Actions OIDC environment
+          if [ -n "$ACTIONS_ID_TOKEN_REQUEST_URL" ]; then
+            echo "✓ OIDC environment detected"
+          else
+            echo "⚠ OIDC environment not detected"
+          fi
+          # Verify npm version meets trusted publishing requirement (11.5.1+)
+          NPM_VERSION=$(npm --version | cut -d. -f1,2)
+          REQUIRED_VERSION="11.5"
+          if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$NPM_VERSION" | sort -V | head -n1)" = "$REQUIRED_VERSION" ]; then
+            echo "✓ npm version meets trusted publishing requirement (11.5.1+)"
+          else
+            echo "⚠ npm version may be too old for trusted publishing (requires 11.5.1+)"
+          fi
 
       - name: Create Release Pull Request or Publish to npm
         id: changesets
@@ -37,4 +66,6 @@ jobs:
           publish: yarn release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # No NPM_TOKEN needed - using trusted publishing via OIDC
+          # The registry-url in setup-node@v4 enables OIDC authentication
+          # npm CLI 11.5.1+ automatically detects OIDC and uses it for publish

AGENTS.md

@@ -36,10 +36,12 @@
 - PRs: clear description, linked issues, screenshots or Storybook links, notes on testing.
 - Required checks: `yarn lint` passes; build succeeds; tests updated/added.
 - Versioning: when changing published package(s), add a Changeset (`yarn changeset`) before merge.
+- Publishing: Releases are automatically published via CI/CD using [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). No npm tokens required. See README.md for setup instructions.
 
 ## Security & Configuration
 - Node `22.9.0` (`.nvmrc`) and Yarn 4 (`packageManager`).
 - Do not commit secrets. Keep large artifacts out of VCS (`dist`, `node_modules`).
+- Publishing uses npm trusted publishers (OIDC) - no long-lived tokens needed.
 - PR previews for Storybook are published via GitHub Pages; verify links in PR comments.
 
 ## Cursor Rules Review
@@ -48,7 +50,7 @@
 - `.cursor/rules/form-component-patterns.mdc`: Remix Hook Form + Zod wrappers, errors, server actions.
 - `.cursor/rules/storybook-testing.mdc`: Storybook play tests, router stub decorator, local/CI flows.
 - `.cursor/rules/monorepo-organization.mdc`: Imports/exports, package boundaries, Turbo/Vite/TS paths.
-- `.cursor/rules/versioning-with-npm.mdc`: npm CLI version bumps (patch-first), CI publishes on merge.
+- `.cursor/rules/versioning-with-npm.mdc`: npm CLI version bumps for quick iterations (patch-first). Primary workflow uses Changesets with automatic CI/CD publishing via npm trusted publishers.
 
 ## Agent OS
 

README.md

@@ -128,3 +128,134 @@ The PR preview is deployed to the `gh-pages` branch in a directory structure lik
 ```
 /pr-preview/pr-[PR_NUMBER]/
 ```
+
+## Publishing
+
+Releases can be published either automatically via CI/CD (using npm trusted publishers) or manually from the command line.
+
+### Automatic Publishing (CI/CD)
+
+When you merge changes to `main` with version updates, the GitHub Actions workflow will automatically publish to npm using [npm trusted publishers](https://docs.npmjs.com/trusted-publishers). This uses OIDC authentication and doesn't require npm tokens.
+
+**Setup required:** Configure trusted publishers on npmjs.com for the `@lambdacurry/forms` package (see setup instructions below).
+
+#### Setting Up Trusted Publishers
+
+1. Go to your package on npmjs.com: https://www.npmjs.com/package/@lambdacurry/forms
+2. Navigate to **Settings** → **Trusted Publisher** section
+3. Click **"Select your publisher"** → **GitHub Actions**
+4. Configure the following:
+   - **Organization or user**: `lambda-curry` (or your GitHub username)
+   - **Repository**: `forms`
+   - **Workflow filename**: `release.yml` (must match exactly, including `.yml` extension)
+5. Click **Save**
+
+The workflow file must exist at `.github/workflows/release.yml` in your repository. Once configured, publishes from the `main` branch will use OIDC authentication automatically.
+
+### Manual Publishing
+
+You can also publish manually from the command line when needed.
+
+### Prerequisites
+
+1. **Ensure you're logged into npm:**
+   ```bash
+   npm login
+   ```
+   You must be logged in as a user with publish permissions for the `@lambdacurry` organization.
+
+2. **Verify your npm credentials:**
+   ```bash
+   npm whoami
+   ```
+
+3. **Ensure you're on the `main` branch and up to date:**
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+
+### Release Process
+
+#### Step 1: Create Changesets (if needed)
+
+If you have changes that need to be documented in the changelog, create a changeset:
+
+```bash
+yarn changeset
+```
+
+Follow the prompts to:
+- Select which packages to include
+- Choose the version bump type (patch, minor, major)
+- Write a summary of the changes
+
+#### Step 2: Version Packages
+
+This updates package versions and generates the changelog:
+
+```bash
+yarn changeset version
+```
+
+This will:
+- Update `packages/components/package.json` with the new version
+- Update `packages/components/CHANGELOG.md` with the new entries
+- Remove the consumed changeset files
+
+#### Step 3: Build and Test
+
+Before publishing, ensure everything builds and tests pass:
+
+```bash
+yarn build
+yarn test
+```
+
+#### Step 4: Publish to npm
+
+Publish the package to npm using changesets:
+
+```bash
+yarn release
+```
+
+This command runs `changeset publish`, which:
+- Runs `yarn build` (via `prepublishOnly` hook in package.json)
+- Publishes `@lambdacurry/forms` to npm (uses npm under the hood)
+- Creates git tags for the release
+- Requires you to be logged into npm (`npm login`)
+
+**Note:** `changeset publish` uses npm CLI internally, so you must be authenticated with npm. The changeset system handles versioning, changelog generation, and publishing all in one workflow.
+
+#### Step 5: Commit and Push
+
+After successful publishing, commit the version changes and push:
+
+```bash
+git add .
+git commit -m "chore(release): publish vX.Y.Z"
+git push origin main
+```
+
+### Alternative: Direct npm Publish (Without Changesets)
+
+If you need to publish without using changesets (e.g., for a hotfix), you can use npm directly:
+
+```bash
+# From the packages/components directory
+cd packages/components
+npm version patch -m "chore: bump version to %s"
+cd ../..
+yarn install  # Update yarn.lock
+yarn workspace @lambdacurry/forms build
+npm publish --workspace=packages/components
+```
+
+**Note:** This bypasses the changeset workflow, so you'll need to manually update the CHANGELOG.md if you want to document the release.
+
+### Troubleshooting
+
+- **"Not logged in" error**: Run `npm login` and verify with `npm whoami`
+- **"Permission denied"**: Ensure your npm user has publish permissions for `@lambdacurry` organization
+- **Build fails**: Fix build errors before publishing. The `prepublishOnly` hook will prevent publishing if the build fails

apps/docs/src/lib/storybook/react-router-stub.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from 'react';
 import type { Decorator } from '@storybook/react-vite';
 import type { ComponentType } from 'react';
 import {
@@ -30,27 +31,40 @@ interface RemixStubOptions {
 export const withReactRouterStubDecorator = (options: RemixStubOptions): Decorator => {
   const { routes, initialPath = '/' } = options;
 
+  // We define the Stub component outside the return function to ensure it's not recreated
+  // on every render of the Story component itself.
+  const CachedStub: ComponentType<{ initialEntries?: string[] }> | null = null;
+  const lastMappedRoutes: StubRouteObject[] | null = null;
+
   return (Story, context) => {
     // Map routes to include the Story component if no Component is provided
-    const mappedRoutes = routes.map((route) => ({
-      ...route,
-      Component: route.Component ?? (() => <Story {...context.args} />),
-    }));
+    const mappedRoutes = useMemo(
+      () =>
+        routes.map((route) => ({
+          ...route,
+          Component: route.Component ?? Story,
+        })),
+      [Story],
+    );
 
     // Get the base path (without existing query params from options)
-    const basePath = initialPath.split('?')[0];
+    const basePath = useMemo(() => initialPath.split('?')[0], []);
 
     // Get the current search string from the actual browser window, if available
     // If not available, use a default search string with parameters needed for the data table
     const currentWindowSearch = typeof window !== 'undefined' ? window.location.search : '?page=0&pageSize=10';
 
     // Combine them for the initial entry
-    const actualInitialPath = `${basePath}${currentWindowSearch}`;
+    const actualInitialPath = useMemo(() => `${basePath}${currentWindowSearch}`, [basePath, currentWindowSearch]);
 
     // Use React Router's official createRoutesStub
-    const Stub = createRoutesStub(mappedRoutes);
+    // We memoize the Stub component to prevent unnecessary remounts of the entire story
+    // when the decorator re-renders.
+    const Stub = useMemo(() => createRoutesStub(mappedRoutes), [mappedRoutes]);
+
+    const initialEntries = useMemo(() => [actualInitialPath], [actualInitialPath]);
 
-    return <Stub initialEntries={[actualInitialPath]} />;
+    return <Stub initialEntries={initialEntries} />;
   };
 };
 

apps/docs/src/lib/storybook/test-utils.ts

@@ -0,0 +1,49 @@
+import { userEvent, within, screen, waitFor } from '@storybook/test';
+
+/**
+ * A robust helper to select an option from a Radix-based Select/Combobox.
+ * Handles portals, animations, and pointer-event blockers.
+ */
+export async function selectRadixOption(
+  canvasElement: HTMLElement,
+  options: {
+    triggerRole?: 'combobox' | 'button';
+    triggerName: string | RegExp;
+    optionName: string | RegExp;
+    optionTestId?: string;
+  },
+) {
+  const canvas = within(canvasElement);
+  const { triggerRole = 'combobox', triggerName, optionName, optionTestId } = options;
+
+  // 1. Find and click the trigger within the component canvas
+  const trigger = await canvas.findByRole(triggerRole, { name: triggerName });
+  if (!trigger) throw new Error(`Trigger with role ${triggerRole} and name ${triggerName} not found`);
+
+  await userEvent.click(trigger);
+
+  // 2. Wait for the listbox to appear in the document body (Portal)
+  // We use a slightly longer timeout for CI stability.
+  const listbox = await screen.findByRole('listbox', {}, { timeout: 3000 });
+  if (!listbox) throw new Error('Radix listbox (portal) not found after clicking trigger');
+
+  // 3. Find the option specifically WITHIN the listbox
+  let option: HTMLElement | null = null;
+  if (optionTestId) {
+    option = await within(listbox).findByTestId(optionTestId);
+  } else {
+    option = await within(listbox).findByRole('option', { name: optionName });
+  }
+
+  if (!option) throw new Error(`Option ${optionName || optionTestId} not found in listbox`);
+
+  // 4. Click the option
+  // pointerEventsCheck: 0 is used to bypass Radix's temporary pointer-event locks during animations
+  await userEvent.click(option, { pointerEventsCheck: 0 });
+
+  // 5. Verify the dropdown closed (optional but ensures stability)
+  await waitFor(() => {
+    const listbox = screen.queryByRole('listbox');
+    if (listbox) throw new Error('Listbox still visible');
+  });
+}

apps/docs/src/remix-hook-form/calendar-with-month-year-select.stories.tsx

@@ -86,7 +86,7 @@ const ControlledCalendarWithFormExample = () => {
   });
 
   const [dropdown, setDropdown] = React.useState<'dropdown' | 'dropdown-months' | 'dropdown-years'>('dropdown');
-  const [date, setDate] = React.useState<Date | undefined>();
+  const [date, setDate] = React.useState<Date | undefined>(new Date(2025, 5, 12));
 
   const dropdownOptions = [
     { label: 'Month and Year', value: 'dropdown' },