# @webflow/data-types

Common types and utilities for building Webflow code components. This package provides the `props` utility for defining component properties, TypeScript types for component definitions, and enums for framework and environment constants.

## Installation

```bash
npm i @webflow/data-types
```

## Usage

### Defining Component Props

The `props` utility provides type-safe constructors for all supported prop types. Each prop type corresponds to a different input interface in the Webflow Properties panel.

#### Basic Example

```tsx
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";

function Button({ text, link }) {
  return (
    <a href={link?.href} target={link?.target}>
      {text}
    </a>
  );
}

export default declareComponent(Button, {
  name: "Button",
  props: {
    text: props.Text({ name: "Button Text", defaultValue: "Click me" }),
    link: props.Link({ name: "Link" }),
  },
});
```

### Available Prop Types

#### Text / String

Plain text input, provided to the component as a `string`.

```tsx
props.Text({
  name: "Label",
  defaultValue: "Hello World",
  group: "Content", // Optional: organize props in groups
  tooltip: "The button label", // Optional: help text
});

// Alias
props.String({ name: "Label" });
```

#### Id

Element ID input, provided to the component as a `string`. No default value allowed.

```tsx
props.Id({
  name: "Element ID",
  tooltip: "Unique identifier for the element",
});
```

#### Link

Link destination and behavior, provided as an object:

```tsx
props.Link({ name: "Destination" });

// Runtime value:
// {
//   href: string;
//   target?: "_self" | "_blank" | string;
//   preload?: "prerender" | "prefetch" | "none" | string;
// }
```

#### Image

Image asset selector, provided as an object:

```tsx
props.Image({ name: "Hero Image" });

// Runtime value:
// {
//   src: string;
//   alt?: string;
// }
```

#### Visibility

Boolean visibility toggle, provided as a `boolean`.

```tsx
props.Visibility({
  name: "Show Element",
  defaultValue: true,
});
```

#### Slot / Children

Slot for child components, provided as a node (e.g., `ReactNode` for React).

```tsx
props.Slot({ name: "Content" });

// Alias
props.Children({ name: "Content" });
```

#### RichText

Rich text editor input, provided as a string.

```tsx
props.RichText({
  name: "Description",
  defaultValue: "<p>Default content</p>",
});
```

#### Number

Numeric input with optional constraints, provided as a `number`.

```tsx
props.Number({
  name: "Count",
  defaultValue: 5,
  min: 0, // Optional: minimum value (clamped)
  max: 100, // Optional: maximum value (clamped)
  decimals: 2, // Optional: max decimal places (rounded)
});
```

#### Variant

Dropdown selector for visual variants, provided as a `string`.

```tsx
props.Variant({
  name: "Style",
  options: ["Primary", "Secondary", "Tertiary"],
  defaultValue: "Primary", // Optional: defaults to first option
});
```

#### Boolean

Boolean toggle with custom labels, provided as a `boolean`.

```tsx
props.Boolean({
  name: "Enabled",
  defaultValue: false,
  trueLabel: "On", // Optional: label for true state
  falseLabel: "Off", // Optional: label for false state
});
```

#### TextNode

Text node input, provided as a string.

```tsx
props.TextNode({
  name: "Content",
  defaultValue: "Default text",
  multiline: true, // Optional: allow multiple lines
});
```

#### Attributes

Custom element attributes, provided to the component as a `Record<string, string>` that can be spread onto an element. No default value allowed.

```tsx
props.Attributes({
  name: "Attributes",
  group: "Custom attributes", // Optional
  tooltip: "Spread onto the root element", // Optional
});

// Runtime value (example):
// { "data-x": "y", "aria-label": "Save" }
```

### Common Options

All prop types support these common options:

- **`name`** (required): Display name in the Properties panel
- **`group`** (optional): Group name for organizing props
- **`tooltip`** (optional): Help text shown in the Properties panel
- **`defaultValue`** (optional): Default value for the prop (not available for `Id`, `Link`, `Image`, `Slot`, and `Attributes` types)

## API Reference

### `props`

An object containing factory functions for creating component props.

**Available Methods:**

- `props.Text(options)` / `props.String(options)` - Plain text input
- `props.Id(options)` - Element ID input
- `props.Link(options)` - Link destination and behavior
- `props.Image(options)` - Image asset selector
- `props.Visibility(options)` - Boolean visibility toggle
- `props.Slot(options)` / `props.Children(options)` - Slot for child components
- `props.RichText(options)` - Rich text editor input
- `props.Number(options)` - Numeric input with constraints
- `props.Variant(options)` - Dropdown selector for variants
- `props.Boolean(options)` - Boolean toggle with custom labels
- `props.TextNode(options)` - Text node input
- `props.Attributes(options)` - Custom element attributes (spread onto an element)

### TypeScript Types

This package exports comprehensive TypeScript types for building type-safe components. The most important ones are:

- **`ComponentDefinition<ComponentType, NodeType, Props>`** - Complete component definition
- **`ComponentClientRendererFactory<ComponentType, RootType, NodeType>`** - Client renderer factory type
- **`ComponentServerRendererFactory<ComponentType, Stream, StreamOptions, NodeType, StringOptions>`** - Server renderer factory type
- **`BundleConfigOverrides`** - Webpack configuration overrides for custom builds

## License

MIT