@srsa/svelte-components

Shared Svelte 5 component library for SRS Acquiom micro-frontends.

Installation

npm install @srsa/svelte-components

Peer dependency: svelte ^5.0.0. Design tokens come from @srsa/ads-design-tokens.

Quick start

<script lang="ts">
  import { Button, Chip } from '@srsa/svelte-components';
</script>

<Button variant="primary">Save</Button>
<Chip label="Active" variant="success" />

Everything is exported from the package root. Each component also has a subpath export for tree-shaking:

import { Avatar } from '@srsa/svelte-components/Avatar';
import { useSortState } from '@srsa/svelte-components/utils/sort';

Component index

Load only the doc for the component you need. Each file has the import, usage, props, test ids and gotchas.

| Component | Use it for | Docs | | ------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Avatar | Circular avatar with initials, image or fallback icon; optional tooltip | Avatar | | Button | Button or link with variants (primary, secondary, tertiary, destructive) and icons | Button | | Checkbox | Styled checkbox with label | Checkbox | | Chip | Compact pill tag or badge with semantic color variants and sizes | Chip | | DateBadge | Compact month/day date badge | DateBadge | | ErrorBanner | Error alert with a refresh action | ErrorBanner | | FileDropzone | Drag-and-drop file selection with validation | FileDropzone | | Input | Text input with leading and trailing icon slots | Input | | MultiSelectDropdown | Floating multi-select menu with a checkbox-style option list | MultiSelectDropdown | | Pagination | Page size selector and prev/next navigation | Pagination | | SelectDropdown | Native select with a chevron indicator | SelectDropdown | | SortableColumnHeader | Clickable table sort header with a directional icon | SortableColumnHeader | | TableCell | Table cell with alignment and emphasis variants | TableCell | | TableRow | Interactive table row with selection state | TableRow | | TableRowCount | Live-region row-count footer | TableRowCount | | Toast + useToastState() | Auto-dismiss notification banner | Toast | | Toggle | Toggle switch with label | Toggle | | Tooltip | Hover/focus tooltip with auto-flip, portaled to document.body by default | Tooltip |

Composing a full table (rows, cells, sorting, pagination): Table.

Other exports:

| Export | Use it for | Docs | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------- | | useSortState, sortArray, compare* | Client-side table sorting | utils | | formatCellValue, formatNumber, formatCurrency, formatDate, maskLast4, maskFull | Display formatting | utils | | portal | Svelte action that moves a node to document.body (for your own overlays) | utils | | CheckIcon, ChevronDownIcon, SortIcon | Icons used by the components | import { ChevronDownIcon } from '@srsa/svelte-components/icons' |

SCSS styles

@use '@srsa/svelte-components/styles/_tokens.scss' as tokens;
@use '@srsa/svelte-components/styles/_reset.scss' as *;

.my-component {
  color: tokens.$color-brand-black;
  font-family: tokens.$font-family-text;
  @include reset;
}

Development

npm install          # Install dependencies
npm run dev          # Dev server
npm test             # Run tests
npm run test:unit    # Run tests with coverage (fails under 90% lines; report in coverage/)
npm run package      # Build package
npm run check        # Type check
npm run lint         # Lint (npm run lint:fix to autofix)
npm run format       # Format with Prettier (npm run format:check to verify)
npm run storybook    # Storybook on :6006

Rules

These come from real problems we already fixed. Follow them so they stay fixed.

1. Test ids. Every component takes dataTestid?: string, rendered as data-testid.
   • Inner parts derive from it: ${dataTestid}-<part>, per-item ${dataTestid}-<part>-${value}. Derived ids are omitted (undefined) when dataTestid is unset.
   • Put data-testid before {...restProps} so a raw data-testid passed by the consumer wins.
   • If rest props land on a wrapper but the interactive element is nested, add a <part>Props passthrough (e.g. triggerProps) spread before the component's own aria-* and handlers, so the component's win.
   • List the derived parts in the @component header and in the component's doc.
2. One source tree. Components, icons, styles and utils live only under src/lib/. Never create parallel top-level src/components, src/icons, src/styles or src/utils folders. We removed exactly that duplicate once.
3. New component checklist. Under src/lib/components/<Name>/: the .svelte file with an @component header, an exported <Name>Props type, index.ts exporting the component and the type, the export in src/lib/index.ts, a package.json subpath export, a *.stories.svelte, a spec, a docs/components/<Name>.md, and a row in the Component index above.
4. Tests. Specs go in tests/unit/components/ or tests/unit/utils/ and import from ../../../src/lib. CI fails under 90% line coverage. Content portaled to document.body (MultiSelectDropdown panel, Tooltip bubble) must be queried with screen, not the render container. Use fireEvent (there is no user-event). jsdom has no element.animate, so stub it when testing transitions.
5. Lint.
   • Don't leave svelte-ignore comments the compiler no longer needs.
   • Don't use {@html} on constant markup; inline the SVG instead.
   • Every eslint-disable needs a written reason and the narrowest scope.
   • Use svelte/prefer-const, not core prefer-const, in .svelte files (already configured).
6. Packaging. package.json exports and files must point at dist/, never src/. Run npm run package and npm pack --dry-run after touching them.
7. Docs. Keep this README thin: it describes the project and routes to docs. Component details belong in docs/components/<Name>.md. Update that file in the same change that alters a component's props or test ids.
8. CI gates. check, lint, format:check, test:unit and audit are all required. Run npm run format before committing. Don't add continue-on-error.