@ssejal8/recipe-ui-kit 0.1.0 → 0.1.1

package/packages/recipe-kit-stencil/README.md

@@ -1,185 +0,0 @@
-# recipe-kit-stencil
-
-Framework-agnostic web components for recipe discovery, favorites and meal-planning UIs, built with [StencilJS](https://stenciljs.com/).
-
-The library ships **standard custom elements**, so it works in SvelteKit, React, Vue, Angular or plain HTML with no framework-specific wrapper. It is consumed by the [Recipe Finder & Meal Planner](https://github.com/sejal-sharma/recipe-ui) SvelteKit application.
-
-```
-npm install recipe-kit-stencil
-```
-
----
-
-## Quick start
-
-### 1. Register the elements
-
-```js
-import { defineCustomElements } from 'recipe-kit-stencil/loader';
-
-defineCustomElements();
-```
-
-`defineCustomElements()` registers every tag lazily — the code for a component is only fetched when that tag first appears in the DOM.
-
-### 2. Load the design tokens
-
-```js
-import 'recipe-kit-stencil/dist/recipe-kit/recipe-kit.css';
-```
-
-This stylesheet defines the `--rk-*` custom properties. Because custom properties inherit through the shadow boundary, it is the single place to re-theme the whole library.
-
-### 3. Use the elements
-
-```html
-<rk-recipe-card
-  recipe-id="52772"
-  name="Teriyaki Chicken Casserole"
-  image="https://…/teriyaki.jpg"
-  category="Chicken"
-  area="Japanese"
-  minutes="45"
->
-  <rk-badge tone="accent" small>weeknight</rk-badge>
-  <button slot="actions">Add to plan</button>
-</rk-recipe-card>
-```
-
-### SSR / SvelteKit note
-
-Custom elements are a browser API, so registration must happen on the client only:
-
-```svelte
-<script>
-  import { browser } from '$app/environment';
-  import { onMount } from 'svelte';
-
-  onMount(async () => {
-    const { defineCustomElements } = await import('recipe-kit-stencil/loader');
-    await defineCustomElements();
-  });
-</script>
-```
-
-Unknown tags render as inert elements during SSR and hydrate once the definitions land.
-
----
-
-## Components
-
-| Tag | Purpose | Key events |
-| --- | --- | --- |
-| `<rk-search-bar>` | Debounced search field with clear button and an `actions` slot | `rkSearch`, `rkClear` |
-| `<rk-chip>` | Selectable / dismissible filter chip | `rkChipToggle`, `rkChipDismiss` |
-| `<rk-segmented-control>` | Single-select segmented control (sorting, view switching) | `rkSegmentChange` |
-| `<rk-recipe-card>` | Recipe tile with favorite toggle, badges slot and actions slot | `rkCardSelect`, `rkFavoriteToggle` |
-| `<rk-rating>` | Star rating, read-only or interactive | `rkRatingChange` |
-| `<rk-badge>` | Small slot-driven label with tone/variant options | — |
-| `<rk-tag-input>` | Tag / token editor with de-duplication and a max-tags cap | `rkTagsChange` |
-| `<rk-meal-slot>` | One planner cell: add target, filled slot, and drop zone | `rkMealAdd`, `rkMealSwap`, `rkMealRemove`, `rkMealOpen`, `rkMealDrop` |
-| `<rk-modal>` | Accessible dialog with focus trap, Escape handling and slots | `rkModalClose` |
-| `<rk-empty-state>` | Empty / error placeholder with an actions slot | — |
-
-Per-component prop, event, slot and CSS-part tables are generated from source into each component folder — see [`src/components`](./src/components).
-
----
-
-## Design principles
-
-**Primitive props over object props.** `<rk-recipe-card>` takes `name`, `image`, `category` … as separate primitive properties rather than one `recipe` object. Primitives round-trip through HTML attributes, so the component is usable from plain markup in any framework.
-
-**Complex props accept a string fallback.** `rk-segmented-control.options` and `rk-tag-input.values` are arrays. Assign them as DOM properties for the normal path; both also parse a JSON-encoded (or comma-separated) string attribute for consumers that cannot set properties.
-
-**Components are controlled.** They emit an intent and let the host application own the state. `rkFavoriteToggle` reports the state to move *to*; the app persists it and passes `favorite` back down. Nothing is silently mutated behind the application's back.
-
-**No global CSS leakage.** Every component uses shadow DOM. Styling hooks are exposed deliberately, via `--rk-*` custom properties and `part="…"` attributes.
-
----
-
-## Theming
-
-Override any token on `:root` — or on any ancestor, to scope a theme to a subtree:
-
-```css
-:root {
-  --rk-primary: #7c3aed;
-  --rk-radius-lg: 8px;
-  --rk-font-display: 'Fraunces', serif;
-}
-```
-
-A dark palette is included and activates on `<html data-rk-theme="dark">` (or `data-theme="dark"`).
-
-For finer control, target the exposed shadow parts:
-
-```css
-rk-recipe-card::part(title) {
-  text-transform: uppercase;
-}
-```
-
----
-
-## Events
-
-Every event name is prefixed `rk` and bubbles with `composed: true`, so it can be handled on an ancestor rather than each element:
-
-```js
-document.addEventListener('rkFavoriteToggle', (event) => {
-  const { recipeId, favorite } = event.detail;
-});
-```
-
-Payload types are exported for TypeScript consumers:
-
-```ts
-import type { RkFavoriteToggleDetail, RkMealDropDetail, RkSegmentOption } from 'recipe-kit-stencil';
-```
-
----
-
-## Local development
-
-```bash
-npm install
-npm start          # dev server with the component gallery at src/index.html
-npm run build      # production build + generated docs
-npm test           # spec tests
-```
-
-`npm start` serves a gallery page that renders every component and logs every emitted event — useful for verifying behaviour outside the consuming app.
-
----
-
-## Output targets
-
-| Target | Output | Use case |
-| --- | --- | --- |
-| `dist` | `dist/`, `loader/` | Lazy-loaded elements. The default, and what the SvelteKit app uses. |
-| `dist-custom-elements` | `dist/components/*.js` | Import and register a single component; tree-shakeable. |
-
-```js
-// Single-component import
-import { RkRecipeCard } from 'recipe-kit-stencil/components/rk-recipe-card';
-```
-
----
-
-## Versioning
-
-[Semantic versioning](https://semver.org/):
-
-- **patch** — bug fixes, styling corrections, no API change
-- **minor** — new components, new optional props, new events
-- **major** — renamed or removed props/events/tags, changed event payloads
-
-```bash
-npm run release:patch   # or release:minor / release:major
-```
-
-`prepublishOnly` runs a clean production build, so a published tarball can never contain stale output.
-
-## License
-
-MIT © Sejal Sharma