@academix-admin/forms 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +96 -0
  2. package/package.json +4 -2
package/README.md ADDED
@@ -0,0 +1,96 @@
1
+ # @academix-admin/forms
2
+
3
+ Headless form fields for React: `TextInput`, `SelectField`, `Checkbox` and `RadioGroup`. They use accessible, semantic markup (a real `<label>` tied to its `<input>`, and `aria-invalid` on an error), and you style every part through a `classNames` map. No styles are bundled, so the fields look like your app, not like this package.
4
+
5
+ ```sh
6
+ npm install @academix-admin/forms
7
+ ```
8
+
9
+ React 18 or 19.
10
+
11
+ ## TextInput
12
+
13
+ ```tsx
14
+ import { TextInput } from '@academix-admin/forms';
15
+
16
+ <TextInput
17
+ label="Phone number"
18
+ value={phone}
19
+ onChange={(value) => setPhone(value)}
20
+ keyboardType="tel"
21
+ prefix="+234"
22
+ helperText={error ?? 'We text a code to this number'}
23
+ status={error ? 'error' : 'default'}
24
+ classNames={{ root: s.field, label: s.label, field: s.box, input: s.input, helper: s.helper }}
25
+ />
26
+ ```
27
+
28
+ - **Value:** controlled (`value` and `onChange(value, event)`) or uncontrolled (`defaultValue`).
29
+ - **Decoration:**
30
+ - `label`, `hint` (the placeholder), `prefix` and `suffix`;
31
+ - `helperText` with `status`: `'default'`, `'error'`, `'valid'` or `'info'`;
32
+ - `counter`: `true`, or a function `(length, maxLength) => ReactNode`.
33
+ - **Behaviour:**
34
+ - `keyboardType` sets the phone keyboard: `'text'`, `'numeric'`, `'decimal'`, `'tel'`, `'email'`, `'url'` or `'search'`;
35
+ - `obscureText` with `secureToggle` and `onSecureToggle(revealed)` gives a password field with a show/hide button;
36
+ - `transform` is `'uppercase'` or `'lowercase'`;
37
+ - the standard input attributes: `maxLength`, `pattern`, `autoFocus`, `disabled`, `required`, `readOnly`, `name`, `id`, `autoComplete`, `autoCapitalize`, `enterKeyHint`, `inputMode`.
38
+ - **Escape hatches:** `onFocus`, `onBlur` and `onKeyDown`, a `ref` forwarded to the `<input>`, and `inputProps` spread onto the input.
39
+ - **Parts (`TextInputClassNames`):** `root`, `label`, `field`, `input`, `prefix`, `suffix`, `toggle`, `helper`, `counter`. Also `className`, `style` and `theme` (`'light'` or `'dark'`).
40
+
41
+ ## SelectField
42
+
43
+ A button that looks like a field and opens your picker. Pair it with `@academix-admin/selection-viewer`.
44
+
45
+ ```tsx
46
+ import { SelectField } from '@academix-admin/forms';
47
+
48
+ <SelectField
49
+ label="Country"
50
+ value={country?.name}
51
+ placeholder="Choose a country"
52
+ onOpen={() => picker.open()}
53
+ helperText={error}
54
+ status={error ? 'error' : 'default'}
55
+ />
56
+ ```
57
+
58
+ Props are `label`, `description`, `value`, `placeholder`, `onOpen`, `trailing` (your chevron or icon), `disabled`, `helperText`, `status`, `id`, `name`, `className`, `style` and `theme`. The parts (`SelectFieldClassNames`) are `root`, `label`, `description`, `control`, `trailing` and `helper`.
59
+
60
+ ## Checkbox
61
+
62
+ ```tsx
63
+ import { Checkbox } from '@academix-admin/forms';
64
+
65
+ <Checkbox checked={agreed} onChange={(checked) => setAgreed(checked)}>
66
+ I agree to the terms
67
+ </Checkbox>
68
+ ```
69
+
70
+ `checked` / `defaultChecked`, `onChange(checked, event)`, `children` (the label), `icon` (the tick), plus `disabled`, `required`, `name`, `id`, `value`, `className`, `style` and `theme`. The parts (`CheckboxClassNames`) are `label`, `input`, `box`, `icon` and `text`.
71
+
72
+ ## RadioGroup
73
+
74
+ ```tsx
75
+ import { RadioGroup } from '@academix-admin/forms';
76
+
77
+ <RadioGroup
78
+ name="plan"
79
+ value={plan}
80
+ onChange={setPlan}
81
+ options={[
82
+ { value: 'monthly', label: 'Monthly' },
83
+ { value: 'yearly', label: 'Yearly', disabled: !canYearly },
84
+ ]}
85
+ />
86
+ ```
87
+
88
+ `name`, `value`, `onChange(value)`, `options` (`RadioOption[]`: `value`, `label`, `disabled`), `disabled`, `className`, `style` and `theme`. The value type follows your options (`RadioGroup<'monthly' | 'yearly'>`). The parts (`RadioGroupClassNames`) are `group`, `item`, `itemSelected`, `input`, `content` and `text`.
89
+
90
+ ## Exports
91
+
92
+ `TextInput`, `SelectField`, `Checkbox`, `RadioGroup`, and their types: `TextInputProps`, `TextInputClassNames`, `TextInputStatus`, `TextInputKeyboard`, `SelectFieldProps`, `SelectFieldClassNames`, `SelectFieldStatus`, `CheckboxProps`, `CheckboxClassNames`, `RadioGroupProps`, `RadioGroupClassNames` and `RadioOption`.
93
+
94
+ ## License
95
+
96
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@academix-admin/forms",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Flutter-idiom, headless form-field components (TextInput, SelectField, Checkbox, RadioGroup) — accessible semantic markup, style every slot via a classNames slot-map.",
5
5
  "keywords": [
6
6
  "react",
@@ -50,7 +50,9 @@
50
50
  "build": "tsup",
51
51
  "clean": "rimraf dist",
52
52
  "dev": "tsup --watch",
53
- "typecheck": "tsc --noEmit"
53
+ "typecheck": "tsc --noEmit",
54
+ "test": "vitest run",
55
+ "test:watch": "vitest"
54
56
  },
55
57
  "peerDependencies": {
56
58
  "react": ">=18.0.0",