hisd3-ui-kit 4.7.1 → 5.1.0

package/README.md

@@ -116,7 +116,9 @@ const menuItems = [
 | `HISD3Tabs` | Underlined filter tabs; each item may carry a `count`. |
 | `HISD3Tag` | Uppercase status pill. `variant`: `neutral` (grey, e.g. ACTIVE / IN PATIENT), `soft` (primary tint, e.g. ER PATIENT), `outline` (2px primary border, e.g. OUT PATIENT), `solid`. `tone`: `primary` \| `success` \| `warning` \| `danger` \| `default`. |
 | `HISD3Button` | `variant`: `primary` (filled), `secondary` (default, dark 2px outline), `ghost`, `danger`. Accepts all antd `Button` props (`icon`, `size`, `loading`, …). |
-| `HISD3Input` / `HISD3SearchInput` | 2px-bordered input; the search variant is the grey filled hero field with a leading icon (`compact` for a 48px version). |
+| `HISD3Input` / `HISD3SearchInput` | 2px-bordered input; the search variant is a light field with a leading icon and a visible border, lighter than the page so it never reads as disabled. `size`: `"small"` 32px, `"middle"` 40px (default), `"large"` 56px. Colours: `--hisd3-input-bg`, `--hisd3-input-bg-hover`, `--hisd3-input-border-hover`. |
+| `HISD3Select` | antd `Select` that wraps long text instead of cutting it with "…", and shows an option's `description` on a second line. See [Select](#select). |
+| `HISD3Form*` fields | Every antd data-entry control pre-wrapped in `Form.Item`, with `loading` skeletons. See *Form fields* below. |
 | `HISD3HeaderActions` | Spacing wrapper for the top-right controls; `divided` inserts a rule before the last child. |
 | `HISD3NotificationButton` | Soft-grey circular button with a solid bell glyph and a count pill on its top-right edge; tints to the primary color while its panel is open. Pass `icon` to swap the glyph. Props: `items` (`{ id, title, description, time, unread, avatarSrc, icon, onClick }`), `count` (defaults to the unread tally), `loading`, `size` (default 40), `icon`, `onMarkAllRead`, `onSeeAll`, `emptyText`. |
 | `HISD3AvatarMenu` | Circular avatar button with a small chevron badge (Facebook-style); clicking it opens a menu with the signed-in identity plus Settings and Logout (confirm dialog by default). Falls back to initials on a grey circle when there is no photo. Props: `account`, `avatarSrc`, `settingsUrl` / `onSettings`, `onLogout`, `confirmLogout`, `extraItems`, `shape` (`circle` \| `square`), `size` (default 40), `hideChevron`. |
@@ -201,6 +203,124 @@ logo is used. `HISD3_LOGO_SRC` is exported if you need the mark elsewhere.
 `primary` accepts the brand presets `"brand"` (the logo's gear, `#E5533B`) and
 `"brandBlue"` (its cloud, `#1B6FE0`), any other preset, or a hex value.
 
+## Select
+
+`HISD3Select` is antd's `Select` with two additions, and takes every `Select`
+prop. `HISD3FormSelect` uses it, so both work the same way.
+
+- **Long text wraps** — in the chosen value and in every option — instead of
+  being cut off with "…". On by default; `wrap={false}` turns it off.
+- **`description` on an option** is shown under its label, smaller and muted,
+  in the dropdown and in the box. With `showSearch`, typing matches the label
+  and the description.
+
+`monoLabel` puts the label line in a monospace font, for codes:
+
+```tsx
+<HISD3Select
+  showSearch
+  monoLabel
+  placeholder="Search an account…"
+  options={accounts.map((a) => ({ value: a.code, label: a.code, description: a.title }))}
+/>
+
+<HISD3FormSelect
+  name="accountCode"
+  label="Account"
+  fieldProps={{ showSearch: true, monoLabel: true, options: accountOptions }}
+/>
+```
+
+Your own `optionRender`, `labelRender`, `filterOption` or `optionFilterProp`
+replaces the default. `HISD3SelectLabel` renders the same two-line layout for a
+custom `optionRender` / `labelRender`.
+
+Wrapped rows are not all one height, so `virtual` is off while `wrap` is on.
+For a list of thousands of options, pass `virtual` (or search on the server and
+show a capped list). Tags in `mode="multiple"` stay on one line.
+
+## Form fields
+
+Each `HISD3Form*` field is an antd control inside a `Form.Item`. It takes every
+`Form.Item` prop (`name`, `label`, `rules`, `tooltip`, `extra`, …) plus:
+
+| Prop | |
+| --- | --- |
+| `fieldProps` | Props for the wrapped control (`placeholder`, `options`, `size`, `format`, …). |
+| `loading` | Shows a skeleton in place of the control. The form value is kept. |
+| `loadingProps` | Props for the default `Skeleton.Input`. |
+| `vertical` | Label above the control (`layout="vertical"` for this item). |
+| `bolderLabel` | Semi-bold label; the control text is unchanged. |
+
+| Field | Wraps | Form value |
+| --- | --- | --- |
+| `HISD3FormInput` | `HISD3Input` | string |
+| `HISD3FormPassword` | `Input.Password` | string |
+| `HISD3FormSearch` | `Input.Search` | string |
+| `HISD3FormTextArea` | `Input.TextArea` | string |
+| `HISD3FormOTP` | `Input.OTP` | string |
+| `HISD3FormInputNumber` | `InputNumber` | number |
+| `HISD3FormAutoComplete` | `AutoComplete` | string |
+| `HISD3FormMentions` | `Mentions` | string |
+| `HISD3FormSelect` | `HISD3Select` | value / value[] |
+| `HISD3FormTreeSelect` | `TreeSelect` | value / value[] |
+| `HISD3FormCascader` | `Cascader` | path array |
+| `HISD3FormRadioGroup` | `Radio.Group` | value |
+| `HISD3FormSegmented` | `Segmented` | value |
+| `HISD3FormCheckbox` | `Checkbox` | boolean (`valuePropName="checked"`) |
+| `HISD3FormCheckboxGroup` | `Checkbox.Group` | value[] |
+| `HISD3FormSwitch` | `Switch` | boolean (`valuePropName="checked"`) |
+| `HISD3FormTransfer` | `Transfer` | right-hand keys (`valuePropName="targetKeys"`) |
+| `HISD3FormSlider` | `Slider` | number, or `[min, max]` with `range` |
+| `HISD3FormRate` | `Rate` | number |
+| `HISD3FormColorPicker` | `ColorPicker` | string in `fieldProps.format` (hex by default) |
+| `HISD3FormDatePicker` | `DatePicker` | Dayjs |
+| `HISD3FormRangePicker` | `DatePicker.RangePicker` | `[Dayjs, Dayjs]` |
+| `HISD3FormTimePicker` | `TimePicker` | Dayjs |
+| `HISD3FormTimeRangePicker` | `TimePicker.RangePicker` | `[Dayjs, Dayjs]` |
+| `HISD3FormUpload` | `Upload` | `UploadFile[]` (`valuePropName="fileList"`) |
+| `HISD3FormUploadDragger` | `Upload.Dragger` | `UploadFile[]` |
+
+Upload fields take the trigger as children
+(`<HISD3FormUpload name="files"><HISD3Button>Select file</HISD3Button></HISD3FormUpload>`)
+and use the exported `normalizeUploadFileList` as `getValueFromEvent`. Any
+`Form.Item` prop you pass (`valuePropName`, `getValueFromEvent`, …) overrides
+the field's default.
+
+`ref` goes to the control itself, so `ref.current?.focus()` works.
+Pickers and number inputs fill their column.
+
+```tsx
+<Form form={form} layout="vertical" onFinish={save}>
+  <HISD3FormInput
+    name="lastName"
+    label="Last name"
+    bolderLabel
+    loading={loadingPatient}
+    rules={[{ required: true, message: "Last name is required" }]}
+    fieldProps={{ placeholder: "Dela Cruz", maxLength: 80 }}
+  />
+  <HISD3FormSelect
+    name="gender"
+    label="Gender"
+    fieldProps={{ options: [{ value: "M", label: "Male" }, { value: "F", label: "Female" }] }}
+  />
+  <HISD3FormDatePicker name="birthDate" label="Birth date" fieldProps={{ format: "MM/DD/YYYY" }} />
+  <HISD3FormSwitch name="active" label="Active" />
+</Form>
+```
+
+Wrap a control the kit does not cover with `HISD3FormField` to get the same
+label, spacing and loading behaviour:
+
+```tsx
+<HISD3FormField name="doctor" label="Attending" loading={loading}>
+  <DoctorPicker />
+</HISD3FormField>
+```
+
+`propsinput` on `HISD3FormInput` still works but is deprecated; use `fieldProps`.
+
 ## Drawers and modals — `useDialog`
 
 Open a drawer or modal from anywhere, without the page holding its state. Put