@serenis/icons 2.42.0

package/LICENSE

@@ -0,0 +1,24 @@
+This package contains two categories of content under different licenses:
+
+================================================================================
+1. CUSTOM ICONS — All SVG components authored by Serenis Health S.r.l.
+================================================================================
+
+Licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0
+International (CC BY-NC-ND 4.0).
+
+Copyright (c) 2026 Serenis Health S.r.l.
+
+You are free to share (copy and redistribute) the custom icons in any medium
+or format, provided you give appropriate credit, do not use them for commercial
+purposes, and do not distribute modified versions.
+
+Full license text: https://creativecommons.org/licenses/by-nc-nd/4.0/legalcode
+
+================================================================================
+2. ICONOIR RE-EXPORTS — Icons re-exported from iconoir-react
+================================================================================
+
+Licensed under the MIT License, inherited from the iconoir-react package.
+See https://github.com/iconoir-icons/iconoir/blob/main/LICENSE for the
+original license text.

package/README.md

@@ -0,0 +1,313 @@
+# @serenis/icons
+
+Icon component library for the Serenis design system. Wraps custom SVG icons and re-exports from iconoir-react.
+
+## Install
+
+```bash
+npm install @serenis/icons
+```
+
+Peer dependencies (must be installed by the consuming app):
+
+- `react` >= 19.0.0
+- `@serenis/design-tokens`
+
+## Quick start
+
+```bash
+# Build
+yarn workspace icons build
+
+# Dev (watch mode)
+yarn workspace icons dev
+
+# Typecheck
+yarn workspace icons typecheck
+```
+
+```tsx
+import { Icon, Home, IconHome } from '@serenis/icons'
+import { type IconElement, type IconCommonProps, type IconSize } from '@serenis/icons'
+
+// Option A: Icon wrapper with raw SVG component (dynamic / slotted usage)
+<Icon Svg={Home} colorName="primary" size={24} />
+
+// Option B: Pre-wrapped shorthand (fixed icon usage)
+<IconHome colorName="primary" size={24} />
+```
+
+## Directory structure
+
+```text
+libraries/icons/
+├── src/
+│   ├── components/           # One .tsx file per icon + Icon.tsx wrapper
+│   │   ├── Icon.tsx          # Design-token-aware wrapper
+│   │   ├── Home.tsx          # Example: exports Home + IconHome
+│   │   ├── Agenda.tsx
+│   │   └── ...               # custom icon files
+│   ├── stories/
+│   │   ├── Overview.mdx      # Storybook documentation page
+│   │   ├── Playground.stories.tsx # Storybook playground for all icons
+│   │   └── ...
+│   ├── types.ts              # Shared TypeScript types
+│   └── index.ts              # Public API (re-exports everything)
+├── dist/                     # Built output (gitignored)
+├── tsup.config.ts            # Bundle config
+└── package.json
+```
+
+## Architecture
+
+### Two icon sources
+
+The library ships icons from two sources through a single public API:
+
+| Source             | Where they live                     | `Icon*` shorthand?                |
+| ------------------ | ----------------------------------- | --------------------------------- |
+| **Custom Serenis** | `src/components/*.tsx` (inline SVG) | Yes — e.g. `Home` + `IconHome`    |
+| **Iconoir**        | Re-exported from `iconoir-react`    | No — use via `<Icon Svg={...} />` |
+
+Custom icons are hand-maintained inline SVG React components designed specifically for the Serenis product. Iconoir icons fill gaps for generic UI glyphs (arrows, navigation chrome, utility actions) that don't need custom artwork.
+
+### The `Icon` wrapper
+
+`Icon` is the bridge between raw SVG components and the design token system. It accepts any `IconElement` and applies design-token-based color and size:
+
+```tsx
+const Icon = ({ Svg, colorName, fillColorName, size }: IconProps): JSX.Element | null => {
+  if (Svg == null) {
+    return null
+  }
+
+  return (
+    <Svg
+      color={colorName ? cssvarColor(colorName) : 'currentColor'}
+      fill={fillColorName ? cssvarColor(fillColorName) : 'none'}
+      height={size}
+      width={size}
+    />
+  )
+}
+```
+
+- **`colorName`** — maps to `color` (stroke) via `cssvarColor()` from `design-tokens`. Omitting it defaults to `currentColor`, inheriting from the parent text color.
+- **`fillColorName`** — maps to `fill` via `cssvarColor()`. Omitting it defaults to `none`. Rarely used (stars, a few nav icons).
+- **`size`** — applied to both `width` and `height`.
+
+### Dual export pattern
+
+Every custom icon file exports two things:
+
+```tsx
+// Home.tsx
+export const Home = ({ color, height, width }: IconElementProps) => (
+  <svg ...>...</svg>
+)
+
+export const IconHome = (props: IconCommonProps) => <Icon Svg={Home} {...props} />
+```
+
+1. **`Home`** — the raw SVG component. Use when passing as a reference to the `Icon` wrapper or to component props typed as `IconElement` (e.g. Button's `IconStart`).
+2. **`IconHome`** — pre-wrapped shorthand. Use for direct rendering when you don't need to pass the icon as a reference.
+
+Iconoir icons are only exported as raw components (no `Icon*` shorthand).
+
+## Type system
+
+All types are exported from the package root:
+
+```tsx
+import {
+  type IconElement,
+  type IconElementProps,
+  type IconCommonProps,
+  type IconProps,
+  type IconSize,
+} from '@serenis/icons'
+```
+
+| Type               | Purpose                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `IconSize`         | `12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 120`                     |
+| `IconElementProps` | Low-level contract for SVG components: `{ color, fill, height, width }`                     |
+| `IconElement`      | Any component that accepts `IconElementProps` — use for props that accept an icon reference |
+| `IconCommonProps`  | Token-based API: `{ colorName?, fillColorName?, size }`                                     |
+| `IconProps`        | `IconCommonProps & { Svg?: IconElement }` — the `Icon` wrapper props                        |
+
+### Size scale
+
+| Size             |
+| ---------------- |
+| 12               |
+| 16               |
+| 20               |
+| 24 **(default)** |
+| 32               |
+| 40               |
+| 48               |
+| 56               |
+| 64               |
+| 72               |
+| 80               |
+| 120              |
+
+## Usage patterns
+
+### Direct rendering
+
+```tsx
+// Pre-wrapped shorthand (custom icons only)
+<IconHome colorName="primary" size={24} />
+
+// Icon wrapper (both custom and Iconoir)
+<Icon Svg={Home} colorName="primary" size={24} />
+<Icon Svg={ArrowLeft} colorName="neutral-80" size={24} />
+```
+
+### Passing icons as props
+
+Many `ui` components accept `IconElement` as a prop:
+
+```tsx
+// Button with start icon
+<Button IconStart={Home} kind="primary">Go home</Button>
+
+// Tile with required icon
+<Tile Icon={Shield} title="Security" action={<Button>Configure</Button>} />
+
+// SideBarItem with active/inactive variants
+<SideBarItem Icon={Agenda} IconActive={AgendaSolid} label="Agenda" active={isActive} />
+```
+
+### Active / inactive pattern
+
+Many custom icons have a Solid variant for active states:
+
+```tsx
+<Icon Svg={active ? AgendaSolid : Agenda} colorName={active ? 'primary-50' : 'neutral-110'} size={24} />
+```
+
+Available pairs: `Agenda`/`AgendaSolid`, `Calendar`/`CalendarSolid`, `Chat`/`ChatSolid`, `Clock`/`ClockSolid`, `Codes`/`CodesSolid`, `Delete`/`DeleteSolid`, `Diary`/`DiarySolid`, `Home`/`HomeSolid`, `Menu`/`MenuSolid`, `Patients`/`PatientsSolid`, `Paths`/`PathsSolid`, and all `Path*`/`Path*Solid` therapy path icons.
+
+### Aliasing when names clash
+
+Some icon names conflict with common identifiers. Alias on import:
+
+```tsx
+import { Card as IconCard, Link as IconLink } from '@serenis/icons'
+```
+
+### Inheriting color from parent
+
+Omit `colorName` to use `currentColor` — the icon inherits the parent's text color:
+
+```tsx
+<Text colorName="primary">
+  <Icon Svg={Home} size={24} /> {/* stroke is primary */}
+</Text>
+```
+
+## Accessibility
+
+Icons rendered through the `Icon` wrapper are **decorative by default** — they carry no accessible name or role. Meaning is expected to come from adjacent text or from the parent control's label.
+
+### Icon with text (no extra ARIA needed)
+
+When an icon appears alongside visible text, the text provides the accessible name. No extra attributes are required on the icon:
+
+```tsx
+<Button IconStart={Home} kind="primary">Go home</Button>
+
+<Flex>
+  <Icon Svg={Info} size={24} />
+  <Text>Important information</Text>
+</Flex>
+```
+
+### Icon-only controls need `aria-label`
+
+When an icon is the **sole content** of a clickable control, the parent element must provide an accessible name via `aria-label` or `aria-labelledby`:
+
+```tsx
+<Button IconStart={Delete} kind="tertiary" aria-label="Delete item" />
+
+<Pressable aria-label="Close" onClick={onClose}>
+  <Icon Svg={ActionCloseLine} size={24} />
+</Pressable>
+```
+
+### Why the `Icon` wrapper has no ARIA attributes
+
+The `Icon` component intentionally does not set `aria-hidden`, `role`, or any ARIA attribute. Whether an icon is decorative or meaningful depends on the usage context, which only the caller knows. Callers should:
+
+- Add `aria-label` to the parent control when the icon is the only content
+- Do nothing when adjacent text already conveys the meaning
+- Avoid adding `aria-hidden="true"` to icons that appear alongside text (the text already provides the name)
+
+### ESLint enforcement
+
+The custom ESLint rule `serenis/no-icon-inside-button` (active as `warn` in `libraries/ui`, `apps/web`, `apps/blog`, `apps/website`, `apps/nutrition-blog`) prevents nesting `Icon` or `Icon*` components as children of `Button`. Use the `IconStart` / `IconEnd` props instead — this ensures consistent sizing, loading-state handling, and accessible markup:
+
+```tsx
+// Correct
+<Button IconStart={Home} kind="primary">Go home</Button>
+
+// Incorrect — caught by ESLint
+<Button><Icon Svg={Home} size={24} />Go home</Button>
+```
+
+## How to add a new icon
+
+There is no codegen pipeline — icons are hand-maintained TSX files.
+
+1. **Create the component file** at `src/components/MyIcon.tsx`:
+
+```tsx
+import { type IconCommonProps, type IconElementProps } from '../types'
+import Icon from './Icon'
+
+type Props = IconElementProps
+
+export const MyIcon = ({ color, height, width }: Props) => (
+  <svg fill="none" height={height} viewBox="0 0 24 24" width={width} xmlns="http://www.w3.org/2000/svg">
+    {/* Paste SVG paths here, use color={color} for strokes */}
+  </svg>
+)
+
+export const IconMyIcon = (props: IconCommonProps) => <Icon Svg={MyIcon} {...props} />
+```
+
+1. **Export from `src/index.ts`** (keep alphabetical order):
+
+```tsx
+export { IconMyIcon, MyIcon } from './components/MyIcon'
+```
+
+1. **Build and typecheck**:
+
+```bash
+yarn workspace icons build
+yarn workspace icons typecheck
+```
+
+The new icon will automatically appear in the Storybook Playground story.
+
+## Build
+
+The package is bundled with [tsup](https://tsup.egoist.dev/) into ESM + CJS + TypeScript declarations. Workspace dependencies (`design-tokens`, `iconoir-react`, `react`) are externalized.
+
+## Consumers
+
+- **Apps**: `apps/web` (primary consumer), `apps/blog`, `apps/nutrition-blog`, `apps/website`
+- **Libraries**: `libraries/ui` (Button, Modal, Accordion, Breadcrumbs, FileUploadField, etc.), `libraries/shared-components` (Nav)
+
+## Documentation
+
+- **Storybook**: Overview page and interactive Playground in `apps/design-system`
+- **AGENTS.md**: Agent-oriented API reference and rules — see [AGENTS.md](AGENTS.md)
+
+## License
+
+Custom Serenis SVG icons: CC BY-NC-ND 4.0 — see [LICENSE](./LICENSE) for the full text. Iconoir re-exports retain their upstream MIT license.