@andesine/extensions 0.0.0-stage → 0.5.0

package/dist/solid.d.ts

@@ -0,0 +1,356 @@
+import { Component, JSX } from "solid-js";
+//#region src/solid/protocol.d.ts
+type RequestErrorCode = "invalid_request" | "forbidden" | "too_many_requests" | "user_interaction_required" | "unavailable" | "failed";
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+  [key: string]: JSONValue;
+};
+//#endregion
+//#region src/solid/renderer.d.ts
+/** A node of the serialized view tree; it mirrors the host tree, which has the real DOM. */
+interface ViewNode {
+  id: number;
+  type: string;
+  parent?: ViewNode;
+  children: ViewNode[];
+  callbacks: Map<string, number>;
+}
+export declare const render: (code: () => ViewNode, node: ViewNode) => () => void, effect: <T>(fn: (prev?: T) => T, init?: T) => void, memo: <T>(fn: () => T, equal: boolean) => () => T, createComponent: <T>(Comp: (props: T) => ViewNode, props: T) => ViewNode, createElement: (tag: string) => ViewNode, createTextNode: (value: string) => ViewNode, insertNode: (parent: ViewNode, node: ViewNode, anchor?: ViewNode | undefined) => void, insert: <T>(parent: any, accessor: T | (() => T), marker?: any | null, initial?: any) => ViewNode, spread: <T>(node: any, accessor: (() => T) | T, skipChildren?: boolean) => void, setProp: <T>(node: ViewNode, name: string, value: T, prev?: T | undefined) => T, mergeProps: (...sources: unknown[]) => unknown, use: <A, T>(fn: (element: ViewNode, arg: A) => T, element: ViewNode, arg: A) => T;
+//#endregion
+//#region src/solid/components.d.ts
+interface ParentProps {
+  children?: JSX.Element;
+}
+interface StyleProps {
+  /** Utility classes of the Andesine UnoCSS preset; the extension build generates their CSS. */
+  class?: string;
+}
+interface ButtonBaseProps {
+  variant?: "text" | "solid" | "outlined";
+  color?: "base" | "contrast" | "primary" | "danger" | "success";
+  size?: "small" | "medium";
+  disabled?: boolean;
+  onClick?(): void;
+}
+interface FieldProps {
+  value?: string;
+  placeholder?: string;
+  label?: string;
+  disabled?: boolean;
+  onInput?(value: string): void;
+}
+interface Option {
+  value: string;
+  label: string;
+}
+interface ChoiceProps {
+  value?: string;
+  options: Option[];
+  placeholder?: string;
+  disabled?: boolean;
+  onChange?(value: string): void;
+}
+interface ToggleProps {
+  checked?: boolean;
+  label?: string;
+  disabled?: boolean;
+  onChange?(checked: boolean): void;
+}
+interface StackProps extends ParentProps, StyleProps {
+  direction?: "row" | "column";
+  gap?: Gap;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "between";
+  wrap?: boolean;
+}
+interface GridProps extends ParentProps, StyleProps {
+  columns?: number;
+  gap?: Gap;
+}
+interface BoxProps extends ParentProps, StyleProps {
+  padding?: Gap;
+  background?: "none" | "soft" | "contrast";
+  border?: boolean;
+}
+interface ScrollAreaProps extends ParentProps {
+  maxHeight?: Size;
+}
+interface TextProps extends ParentProps, StyleProps {
+  size?: "xs" | "sm" | "base" | "lg";
+  weight?: "normal" | "medium" | "semibold";
+  tone?: Tone;
+}
+interface HeadingProps extends ParentProps, StyleProps {
+  level?: 1 | 2 | 3;
+}
+interface LinkProps extends ParentProps {
+  /** An `https:` URL within the extension's declared request URLs. */
+  href: string;
+}
+interface BadgeProps extends ParentProps {
+  color?: "base" | "primary" | "danger" | "success";
+}
+interface IconProps {
+  /** An icon class, e.g. `i-lucide:rocket`, or `i-acme:logo?bg` for a colored icon. */
+  name: string;
+  size?: Size;
+  tone?: Tone;
+}
+interface ButtonProps extends ButtonBaseProps, ParentProps {
+  loading?: boolean;
+}
+interface IconButtonProps extends ButtonBaseProps {
+  icon: string;
+  label: string;
+}
+interface InputProps extends FieldProps {
+  type?: "text" | "url" | "number";
+  onEnter?(): void;
+}
+interface TextareaProps extends FieldProps {
+  rows?: number;
+}
+interface ToggleGroupProps {
+  value?: string;
+  options: Option[];
+  disabled?: boolean;
+  onChange?(value: string): void;
+}
+interface ColorInputProps {
+  /** A hex color, e.g. `#ff3617`. */
+  value?: string;
+  disabled?: boolean;
+  onInput?(value: string): void;
+}
+interface TooltipProps extends ParentProps {
+  content: string;
+}
+interface SettingProps extends ParentProps {
+  label: string;
+  description?: string;
+}
+interface ListProps extends ParentProps {
+  addLabel?: string;
+  emptyLabel?: string;
+  disabled?: boolean;
+  onAdd?(): void;
+  onRemove?(index: number): void;
+  onMove?(from: number, to: number): void;
+}
+interface CardProps extends ParentProps {
+  color?: "base" | "contrast" | "soft";
+}
+interface TreeItem {
+  id: string;
+  label: string;
+  icon?: string;
+  /** The parent item ID; top level when unset. */
+  parent?: string;
+}
+interface TreeProps {
+  items: TreeItem[];
+  selected?: string;
+  emptyLabel?: string;
+  onSelect?(id: string): void;
+}
+interface TabsProps extends ParentProps {
+  value?: string;
+  onChange?(value: string): void;
+}
+interface TabProps extends ParentProps {
+  value: string;
+  label: string;
+}
+interface DisclosureProps extends ParentProps {
+  label: string;
+  open?: boolean;
+}
+interface CalloutProps extends ParentProps {
+  tone?: "info" | "warning" | "danger" | "success";
+  title?: string;
+}
+interface StepProps extends ParentProps {
+  title: string;
+}
+interface FigureProps {
+  /** An `https:` image URL within the extension's declared request URLs. */
+  src: string;
+  alt: string;
+  caption?: string;
+}
+interface CodeBlockProps {
+  code: string;
+  language?: string;
+}
+interface TimeAgoProps {
+  /** An ISO date-time. */
+  date: string;
+}
+interface SpinnerProps {
+  size?: Size;
+}
+interface SkeletonProps {
+  height?: Size;
+}
+type Gap = "none" | "small" | "medium" | "large";
+type Size = "small" | "medium" | "large";
+type Tone = "default" | "muted" | "danger" | "success";
+type EmptyProps = Record<string, never>;
+declare const Stack: (props: StackProps) => JSX.Element;
+declare const Grid: (props: GridProps) => JSX.Element;
+declare const Box: (props: BoxProps) => JSX.Element;
+declare const Divider: (props: EmptyProps) => JSX.Element;
+declare const ScrollArea: (props: ScrollAreaProps) => JSX.Element;
+declare const Text: (props: TextProps) => JSX.Element;
+declare const Heading: (props: HeadingProps) => JSX.Element;
+declare const Code: (props: ParentProps) => JSX.Element;
+declare const Link: (props: LinkProps) => JSX.Element;
+declare const Badge: (props: BadgeProps) => JSX.Element;
+declare const Icon: (props: IconProps) => JSX.Element;
+declare const Button: (props: ButtonProps) => JSX.Element;
+declare const IconButton: (props: IconButtonProps) => JSX.Element;
+declare const Input: (props: InputProps) => JSX.Element;
+declare const Textarea: (props: TextareaProps) => JSX.Element;
+declare const Select: (props: ChoiceProps) => JSX.Element;
+declare const Combobox: (props: ChoiceProps) => JSX.Element;
+declare const Checkbox: (props: ToggleProps) => JSX.Element;
+declare const Toggle: (props: ToggleProps) => JSX.Element;
+declare const ToggleGroup: (props: ToggleGroupProps) => JSX.Element;
+declare const ColorInput: (props: ColorInputProps) => JSX.Element;
+declare const Tooltip: (props: TooltipProps) => JSX.Element;
+declare const Setting: (props: SettingProps) => JSX.Element;
+declare const List: (props: ListProps) => JSX.Element;
+declare const Card: (props: CardProps) => JSX.Element;
+declare const Tree: (props: TreeProps) => JSX.Element;
+declare const Tabs: (props: TabsProps) => JSX.Element;
+declare const Tab: (props: TabProps) => JSX.Element;
+declare const Disclosure: (props: DisclosureProps) => JSX.Element;
+declare const Callout: (props: CalloutProps) => JSX.Element;
+declare const Steps: (props: ParentProps) => JSX.Element;
+declare const Step: (props: StepProps) => JSX.Element;
+declare const Figure: (props: FigureProps) => JSX.Element;
+declare const CodeBlock: (props: CodeBlockProps) => JSX.Element;
+declare const TimeAgo: (props: TimeAgoProps) => JSX.Element;
+declare const Spinner: (props: SpinnerProps) => JSX.Element;
+declare const Skeleton: (props: SkeletonProps) => JSX.Element;
+/** Where an element view shows the element's editable content (element views only). */
+declare const ContentSlot: (props: EmptyProps) => JSX.Element;
+//#endregion
+//#region src/solid/runtime.d.ts
+type ExtensionViews = Record<string, Component<never>>;
+/**
+ * Starts the extension frontend in its sandbox worker. `entries` maps the view entries that the
+ * manifest names to Solid components; each view receives its host props as reactive props.
+ */
+declare const startExtension: (entries: ExtensionViews) => void;
+//#endregion
+//#region src/solid/actions.d.ts
+/** Copies text; the host shows a fallback dialog if the browser refuses. */
+declare const copyText: (text: string) => Promise<void>;
+/** Downloads a text file, for example `downloadFile("andesine.config.ts", source)`. */
+declare const downloadFile: (name: string, text: string, type?: string) => Promise<void>;
+/** Opens an `https:` URL in a new tab; URLs outside the declared URLs need confirmation. */
+declare const openURL: (url: string) => Promise<void>;
+//#endregion
+//#region src/solid/requests.d.ts
+/** A host request failed; `code` says why, for example `user_interaction_required`. */
+declare class ExtensionRequestError extends Error {
+  readonly code: RequestErrorCode;
+  constructor(code: RequestErrorCode, message: string);
+}
+//#endregion
+//#region src/solid/editor.d.ts
+/** A document block in editor JSON, e.g. `{ type: "paragraph", content: [{ type: "text", text: "Hi" }] }`. */
+interface ContentNode {
+  type: string;
+  attrs?: Record<string, JSONValue>;
+  content?: ContentNode[];
+  marks?: Array<{
+    type: string;
+    attrs?: Record<string, JSONValue>;
+  }>;
+  text?: string;
+}
+interface ViewEditor {
+  /** Block action views: replaces the blocks the action was opened for. */
+  replace(content: ContentNode[]): Promise<void>;
+  /** Block action views: inserts blocks after those the action was opened for. */
+  insertAfter(content: ContentNode[]): Promise<void>;
+  /** Element views: updates the element's props; call it from a user interaction. */
+  setElementProps(props: Record<string, JSONValue>): Promise<void>;
+  /** Block action views: closes the view. */
+  close(): Promise<void>;
+}
+/**
+ * Edits the document from the current view. Andesine validates every edit and applies it as the
+ * member's own edit; edits reject with `ExtensionRequestError` when they do not fit.
+ */
+declare const useEditor: () => ViewEditor;
+//#endregion
+//#region src/solid/storage.d.ts
+interface StorageEntry<T extends JSONValue = JSONValue> {
+  key: string;
+  value: T;
+  /** An ISO date-time. */
+  updatedAt: string;
+}
+interface StorageListOptions {
+  /** Only keys that start with the prefix. */
+  prefix?: string;
+  /** Entries after this key, from the previous page. */
+  after?: string;
+  /** At most 100 (the default). */
+  limit?: number;
+}
+interface StoragePage {
+  data: StorageEntry[];
+  hasMore: boolean;
+}
+/**
+ * The extension's JSON key-value storage, shared with its backend. Keys have up to 256
+ * characters; values up to 128 KiB; the storage up to 10,000 entries and 10 MiB. The last write
+ * wins. Failed requests reject with `ExtensionRequestError`.
+ */
+declare const storage: {
+  /** The entry, or null when the key is not set. */
+  get<T extends JSONValue = JSONValue>(key: string): Promise<StorageEntry<T> | null>;
+  /** Creates or replaces an entry; resolves with its update time. */
+  set(key: string, value: JSONValue): Promise<{
+    updatedAt: string;
+  }>;
+  /** Resolves with whether the key was set. */
+  delete(key: string): Promise<boolean>;
+  /** Entries in key order; a page can have fewer entries than `limit` when values are large. */
+  list(options?: StorageListOptions): Promise<StoragePage>;
+};
+//#endregion
+//#region src/solid/context.d.ts
+/** The origin `apiFetch` accepts; use it as the SDK `baseURL`. */
+declare const EXTENSION_API_URL = "https://api.andesine.invalid";
+/**
+ * The configuration's non-secret values, with defaults for unset fields (reactive). Secret
+ * fields are readable only by the extension backend.
+ */
+declare const useConfiguration: <T extends Record<string, JSONValue> = Record<string, JSONValue>>() => () => Partial<T>;
+/** The member's effective permissions for this extension (reactive), e.g. `read:entries`. */
+declare const usePermissions: () => import("solid-js").Accessor<string[]>;
+/** Whether the effective permissions include `permission`; a write permission includes its read. */
+declare const hasPermission: (permission: string) => boolean;
+/**
+ * A fetch implementation for the Andesine SDK: requests go through Andesine with the member's
+ * session, within the effective permissions. Forbidden operations answer with HTTP 403.
+ * @example createClient({ baseURL: EXTENSION_API_URL, fetch: apiFetch })
+ */
+declare const apiFetch: typeof fetch;
+/** The extension's own backend, as declared in the manifest. */
+declare const backend: {
+  /**
+   * Fetches a path of the backend URL with the member's session token in `Authorization`, and
+   * the extension ID and instance API URL in `Andesine-Extension` and `Andesine-Instance`; the
+   * backend verifies them with `verifySession` from `@andesine/sdk/extensions`. Its CORS
+   * configuration must allow these headers.
+   */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+};
+//#endregion
+export { Badge, type BadgeProps, Box, type BoxProps, Button, type ButtonProps, Callout, type CalloutProps, Card, type CardProps, Checkbox, type ChoiceProps, Code, CodeBlock, type CodeBlockProps, ColorInput, type ColorInputProps, Combobox, type ContentNode, ContentSlot, Disclosure, type DisclosureProps, Divider, EXTENSION_API_URL, type EmptyProps, ExtensionRequestError, Figure, type FigureProps, Grid, type GridProps, Heading, type HeadingProps, Icon, IconButton, type IconButtonProps, type IconProps, Input, type InputProps, Link, type LinkProps, List, type ListProps, type Option, type ParentProps, ScrollArea, type ScrollAreaProps, Select, Setting, type SettingProps, Skeleton, type SkeletonProps, Spinner, type SpinnerProps, Stack, type StackProps, Step, type StepProps, Steps, type StorageEntry, type StorageListOptions, type StoragePage, type StyleProps, Tab, type TabProps, Tabs, type TabsProps, Text, type TextProps, Textarea, type TextareaProps, TimeAgo, type TimeAgoProps, Toggle, ToggleGroup, type ToggleGroupProps, type ToggleProps, Tooltip, type TooltipProps, Tree, type TreeItem, type TreeProps, type ViewEditor, apiFetch, backend, copyText, downloadFile, hasPermission, openURL, startExtension, storage, useConfiguration, useEditor, usePermissions };
+//# sourceMappingURL=solid.d.ts.map