vercel-labs/json-render

directives

Pre-built custom directives for json-render — formatting, math, string manipulation, and i18n.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/vercel-labs/json-render --skill directives

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

@json-render/directives

Pre-built custom directives for @json-render/core. Drop them into your catalog and renderer to add formatting, math, string manipulation, and i18n.

Quick Start

typescript
import { standardDirectives } from '@json-render/directives';

// Wire into prompt generation
const prompt = catalog.prompt({ directives: standardDirectives });

// Wire into the renderer (React example)
import { JSONUIProvider, Renderer } from '@json-render/react';

<JSONUIProvider registry={registry} directives={standardDirectives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

To add factory directives like createI18nDirective, spread the array:

typescript
import { standardDirectives, createI18nDirective } from '@json-render/directives';

const directives = [...standardDirectives, createI18nDirective(config)];

Defining Custom Directives

Use defineDirective from @json-render/core:

typescript
import { defineDirective, resolvePropValue } from '@json-render/core';
import { z } from 'zod';

const doubleDirective = defineDirective({
  name: '$double',
  description: 'Double a numeric value.',
  schema: z.object({
    $double: z.unknown(),
  }),
  resolve(value, ctx) {
    const resolved = resolvePropValue(value.$double, ctx);
    return (resolved as number) * 2;
  },
});

Rules:

  • Name must start with $
  • Name must not conflict with built-in keys ($state, $cond, $computed, $template, $item, $index, $bindState, $bindItem)
  • Resolvers should call resolvePropValue on sub-values to support composition

Built-in Directives

$format — Locale-aware value formatting

Formats values using Intl formatters. Supports date, currency, number, and percent.

json
{ "$format": "currency", "value": { "$state": "/cart/total" }, "currency": "USD" }
{ "$format": "date", "value": { "$state": "/user/createdAt" } }
{ "$format": "number", "value": 1234567, "notation": "compact" }
{ "$format": "percent", "value": 0.75 }
{ "$format": "date", "value": { "$state": "/post/createdAt" }, "style": "relative" }

Fields: $format (date | currency | number | percent), value (any expression), locale? (string), currency? (string, default "USD"), notation? (string), style? ("relative" for relative dates), options? (extra Intl options).

$math — Arithmetic operations

json
{ "$math": "add", "a": { "$state": "/subtotal" }, "b": { "$state": "/tax" } }
{ "$math": "round", "a": 3.7 }

Operations: add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs. Unary ops (round, floor, ceil, abs) only use a. Division by zero returns 0.

Fields: $math (operation enum), a? (first operand, default 0), b? (second operand, default 0).

$concat — String concatenation

json
{ "$concat": [{ "$state": "/user/firstName" }, " ", { "$state": "/user/lastName" }] }

Fields: $concat (array of values to resolve and join into a string).

$count — Array/string length

json
{ "$count": { "$state": "/cart/items" } }

Returns .length of arrays or strings, 0 for other types.

Fields: $count (value to count).

$truncate — Text truncation

json
{ "$truncate": { "$state": "/post/body" }, "length": 140, "suffix": "..." }

Fields: $truncate (value to truncate), length? (max chars, default 100), suffix? (string, default "...").

$pluralize — Singular/plural forms

json
{ "$pluralize": { "$state": "/cart/itemCount" }, "one": "item", "other": "items", "zero": "no items" }

Output: "3 items", "1 item", or "no items".

Fields: $pluralize (count value), one (singular label), other (plural label), zero? (zero label).

$join — Join array elements

json
{ "$join": { "$state": "/tags" }, "separator": ", " }

Fields: $join (array to join), separator? (string, default ", ").

createI18nDirective — Internationalization factory

typescript
import { createI18nDirective } from '@json-render/directives';

const tDirective = createI18nDirective({
  locale: 'en',
  messages: {
    en: { "greeting": "Hello, {{name}}!", "checkout.submit": "Place Order" },
    es: { "greeting": "Hola, {{name}}!", "checkout.submit": "Realizar Pedido" },
  },
  fallbackLocale: 'en',
});

Usage in specs:

json
{ "$t": "checkout.submit" }
{ "$t": "greeting", "params": { "name": { "$state": "/user/name" } } }

Fields: $t (translation key), params? (interpolation parameters, values accept expressions).

Config: locale (current locale), messages (Record<locale, Record<key, string>>), fallbackLocale? (fallback when key missing).

Composition

Directives compose naturally — each resolver calls resolvePropValue on its inputs, so directives can wrap other directives or built-in expressions:

json
{
  "$format": "currency",
  "value": { "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } },
  "currency": "USD"
}

Resolves inside-out: $state reads from state, $math multiplies, $format formats as currency.

Wiring into Renderers

All four renderers (React, Vue, Svelte, Solid) accept directives on their provider and createRenderer output:

tsx
// Provider pattern
<JSONUIProvider registry={registry} directives={directives}>
  <Renderer spec={spec} registry={registry} />
</JSONUIProvider>

// createRenderer pattern
const MyRenderer = createRenderer(catalog, components);
<MyRenderer spec={spec} directives={directives} />

For prompt generation, pass the same array:

typescript
const prompt = catalog.prompt({ directives });

Key Exports

ExportPurpose
formatDirective$format directive definition
mathDirective$math directive definition
concatDirective$concat directive definition
countDirective$count directive definition
truncateDirective$truncate directive definition
pluralizeDirective$pluralize directive definition
joinDirective$join directive definition
createI18nDirectiveFactory for $t i18n directive
standardDirectivesArray of all 7 non-factory directives
I18nConfigType for i18n configuration

Tâches connexes

du même dépôt

Autres Skills

Tous les Skills