recipe-ui-kit

Reusable recipe UI web components, built with Stencil. Framework-agnostic custom elements — usable from SvelteKit, React, Vue, or plain HTML.

Published as @shivamtiwari777/recipe-ui-kit — a scoped package under a personal npm scope. publishConfig: { "access": "public" } is set, so a plain npm publish works; without it a scoped package would default to private and fail with 402 Payment Required. See PUBLISHING.md.

Components

| Tag | Purpose | |---|---| | rk-button | Themed button with variants, sizes, loading state, and icon slots | | rk-recipe-card | Recipe summary card with its own image fallback and a favourite toggle | | rk-day-plan | One day of a meal planner, rendering a list of planned meals | | rk-dialog | Modal dialog with focus trap, Escape and backdrop handling, focus restoration |

Full API tables — every property, event, slot, shadow part and CSS custom property — are generated from source into each component's readme.md under src/components/. They are regenerated on every build with strict: true, so an undocumented member fails the build and the docs cannot drift.

Install

npm install @shivamtiwari777/recipe-ui-kit

Register the elements

Once, near your app's entry point, on the client only:

import { defineCustomElements } from '@shivamtiwari777/recipe-ui-kit';

defineCustomElements();

Then wait for each tag before treating it as interactive, so nothing renders as un-upgraded markup:

await Promise.all(
  ['rk-button', 'rk-recipe-card', 'rk-day-plan', 'rk-dialog'].map(t => customElements.whenDefined(t)),
);

These components cannot be server-rendered. Stencil's SSR support covers its React and Vue output targets only, and shadow DOM is invisible until JavaScript loads — so register client-side and render a placeholder until ready.

Passing data in: properties, not attributes

This is the part most likely to be got wrong. HTML attributes carry strings only. Anything else — tags on a card, meals on a day — must be assigned as a JS property on the element instance:

const day = document.querySelector('rk-day-plan');
day.day = 'Monday';
day.meals = [{ entryId: 'e1', recipeId: '52785', title: 'Dal fry' }];

Written as an attribute, an array becomes the string "[object Object]". The component still renders — just with garbage — so this fails quietly. Stencil's generated docs mark property-only inputs with -- in the Attribute column; tags and meals are both marked that way.

In a framework, do this on the element reference after mount. For SvelteKit specifically, see the wrapper layer in the sibling recipe-app/src/lib/stencil/ for a working pattern.

Getting data out: custom events

Every component reports outward with a CustomEvent and mutates nothing of its own. The caller applies the change and passes fresh data back down, so your store stays the single source of truth.

card.addEventListener('rkFavoriteToggle', event => {
  const { recipeId, favorite } = event.detail; // `favorite` is the REQUESTED new state
  // apply to your own state, then re-render
});

Events: rkPress, rkRecipeOpen, rkFavoriteToggle, rkMealAdd, rkMealRemove, rkMealOpen, rkDismiss.

Two things worth knowing:

• rk-dialog never closes itself. It emits rkDismiss with a reason (close-button | backdrop | escape) and leaves the decision to you. That is what makes an "are you sure?" flow possible — you may want to ignore a backdrop click while asking.
• Planner events carry entryId as well as recipeId. The same recipe can be planned twice, so the entry id is what makes "remove this one" unambiguous.

Theming

Every component reads CSS custom properties and hardcodes no colour. Override any of the 39 tokens:

:root {
  --rk-color-accent: #0f766e;
  --rk-radius-lg: 8px;
}

Dark values apply automatically via prefers-color-scheme, and can be forced either way with data-rk-theme="dark" or data-rk-theme="light" on any ancestor — which is what a host app's theme switch should set. An explicit choice beats the OS preference.

To use the tokens in your app's own chrome (not just inside the components), import the stylesheet:

import '@shivamtiwari777/recipe-ui-kit/theme.css';

Shadow DOM keeps component internals isolated. Where deeper styling is genuinely needed, key internals expose part attributes: button, spinner, card, title, favorite, panel, backdrop.

Develop

npm install
npm start          # dev server with the harness at src/index.html
npm run build      # production build + regenerated component docs + theme.css

The harness renders every component with real records from TheMealDB's Indian recipes, applies every event to local state, and logs each event's detail. It includes one recipe with no image so the card's placeholder path is exercised rather than assumed. There is no test suite in this project, so the harness is the verification surface — it is built to demonstrate the contract, not to look pretty.

Publishing

Not automated deliberately — the maintainer publishes. See PUBLISHING.md.

Versioning follows semver. Renaming or removing a property, event, slot, shadow part, documented CSS custom property, or tag name is a breaking change and takes a major bump. Additions are minor.