@molecule/app-join-code-react 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,160 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:51:08.777Z
+-->
+
+# @molecule/app-join-code-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+React multi-slot join-code input.
+
+Exports:
+
+- `<JoinCode>` — N-slot single-character input with auto-advance, paste-to-fill,
+  alphabet validation, and `onComplete` notification.
+- `JoinCodeProps`, `JoinCodeAlphabet` — public types.
+
+Companion locale bond: `@molecule/app-locales-join-code`.
+
+## Quick Start
+
+```tsx
+import { JoinCode } from '@molecule/app-join-code-react'
+
+;<JoinCode
+  length={6}
+  alphabet="alphanumeric"
+  onChange={(code) => setCode(code)}
+  onComplete={(code) => verifyCode(code)}
+/>
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-join-code-react @molecule/app-i18n @molecule/app-react @molecule/app-ui react
+npm install -D @types/react
+```
+
+## API
+
+### Interfaces
+
+#### `JoinCodeProps`
+
+Props for the `<JoinCode>` component.
+
+```typescript
+interface JoinCodeProps {
+  /** Number of slots / characters in the code. Defaults to `6`. */
+  length?: number
+  /**
+   * Controlled value. When provided, the component is controlled and ignores
+   * `defaultValue`. The value may be shorter than `length`; missing slots
+   * render empty.
+   */
+  value?: string
+  /**
+   * Initial value when uncontrolled. Ignored when `value` is provided.
+   */
+  defaultValue?: string
+  /**
+   * Called whenever the code changes (typing, paste, backspace).
+   * The argument is the *current* code (may be shorter than `length`).
+   */
+  onChange?: (code: string) => void
+  /**
+   * Called when the code reaches the configured `length` and every character
+   * passes alphabet validation. Fires once per completion (re-fires when the
+   * code is cleared and re-completed).
+   */
+  onComplete?: (code: string) => void
+  /**
+   * Whether to fire `onComplete` automatically when `length` is reached.
+   * Defaults to `true`.
+   */
+  autoSubmit?: boolean
+  /** Allowed character set. Defaults to `'alphanumeric'`. */
+  alphabet?: JoinCodeAlphabet
+  /** Whether the input is disabled. */
+  disabled?: boolean
+  /** Optional className applied to the outer wrapper. */
+  className?: string
+}
+```
+
+### Types
+
+#### `JoinCodeAlphabet`
+
+Alphabet a join code may use.
+
+- `'numeric'` — `0-9` only.
+- `'letters'` — `A-Z` only (case-insensitive on input, normalised to upper-case).
+- `'alphanumeric'` — `A-Z` + `0-9` (case-insensitive, normalised to upper-case).
+
+```typescript
+type JoinCodeAlphabet = 'numeric' | 'letters' | 'alphanumeric'
+```
+
+### Functions
+
+#### `JoinCode(props)`
+
+Multi-slot join-code input. Renders one single-character `<input>` per slot
+with auto-advance focus, backspace-to-previous, and paste-to-fill behaviour.
+
+- **Controlled** when `value` is provided; the parent must update it via
+  `onChange`. The displayed code is clamped to `length` characters.
+- **Uncontrolled** otherwise; `defaultValue` seeds the initial state.
+
+Calls `onComplete(code)` once the code reaches `length` characters and every
+character matches `alphabet`. The fire is suppressed while `autoSubmit`
+is `false`.
+
+All user-visible text (label, slot aria-labels) flows through `t()` so
+apps can localise via the companion `@molecule/app-locales-join-code`
+bond.
+
+Styling is delegated to `getClassMap()` — no Tailwind utility strings live
+in this package.
+
+```typescript
+function JoinCode(props: JoinCodeProps): ReactElement<unknown, string | JSXElementConstructor<any>>
+```
+
+- `props` — See `JoinCodeProps`.
+
+**Returns:** The rendered join-code input.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-i18n` ^1.0.1
+- `@molecule/app-react` ^1.0.1
+- `@molecule/app-ui` ^1.0.1
+- `react` ^18.0.0 || ^19.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-i18n`
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `react`
+
+## Translations
+
+Translation strings are provided by `@molecule/app-locales-join-code`.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@molecule/app-join-code-react",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Multi-slot join-code input with auto-advance, paste-to-fill, and alphabet validation. Used for live quiz join, virtual classroom room codes, and similar short-code entry UX.",
+  "homepage": "https://www.molecule.dev/packages/app-join-code-react",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +18,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -25,16 +27,21 @@
     "react"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/features/join-code-react"
+  },
   "peerDependencies": {
-    "@molecule/app-i18n": "^1.0.0",
-    "@molecule/app-react": "^1.0.0",
-    "@molecule/app-ui": "^1.0.0",
+    "@molecule/app-i18n": "^1.0.1",
+    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-ui": "^1.0.1",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@molecule/app-i18n": "1.0.0",
-    "@molecule/app-react": "1.0.0",
-    "@molecule/app-ui": "1.0.0",
+    "@molecule/app-i18n": "1.0.2",
+    "@molecule/app-react": "1.5.1",
+    "@molecule/app-ui": "1.1.1",
     "@testing-library/react": "16.3.2",
     "@types/node": "26.1.2",
     "@types/react": "19.2.17",
@@ -42,6 +49,6 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   }
 }