@ossy/types 0.3.2 → 0.4.1

package/build/index.d.ts

@@ -1,10 +1,17 @@
+/**
+ * One input in a {@link ResourceTemplate}. The `name` is the key used in `Resource.content` for
+ * template-backed documents (alongside the editor’s input `type`, e.g. `text`, `textarea`, `richtext`, `select`).
+ */
 interface Field {
+    /** Display label; UI may fall back to `name` when omitted. */
     label?: string;
+    /** Key stored in the resource’s `content` object. */
     name: string;
     type: string;
     description?: string;
     placeholder?: string;
     required?: boolean;
+    /** Allowed values for `select` / multiselect-style field types. */
     options?: string[];
 }
 
@@ -87,34 +94,22 @@ interface ColorPalette {
     } | undefined;
 }
 /**
- * Surface definitions - base surface colors and gradients.
+ * Surface definitions — flat preview strings (docs / tooling).
+ * Aligns with `surfaces` keys: base, primary, accent.
  */
 interface SurfaceDefinitions {
-    primary?: CssValue;
-    secondary?: CssValue;
     base?: CssValue;
+    primary?: CssValue;
     accent?: CssValue;
-    'radial-gradient'?: CssValue;
-    'linear-gradient'?: CssValue;
-    decorated?: CssValue;
     [key: string]: CssValue | undefined;
 }
 /**
- * Surfaces - named surface variants for components.
- * Keys map to data-surface attribute values.
+ * Surfaces — named variants for `[data-surface="…"]`.
+ * Canonical set: base, primary, accent.
  */
 interface SurfacesMap {
     base?: SurfaceVariant;
     primary?: SurfaceVariant;
-    secondary?: SurfaceVariant;
-    decorated?: SurfaceVariant;
-    'alt-primary'?: SurfaceVariant;
-    'alt-secondary'?: SurfaceVariant;
-    'radial-gradient'?: SurfaceVariant;
-    'linear-gradient'?: SurfaceVariant;
-    'alt-glass'?: SurfaceVariant;
-    info?: SurfaceVariant;
-    danger?: SurfaceVariant;
     accent?: SurfaceVariant;
     [key: string]: SurfaceVariant | undefined;
 }
@@ -153,23 +148,52 @@ interface Theme {
  */
 type ThemeId = 'cloud-light' | 'cloud-dark';
 
-interface Resource<T = any> {
+/**
+ * A resource is one item in a workspace tree (folder, structured document, media file, job record, etc.).
+ *
+ * **Relation to {@link ResourceTemplate}** — For document-like resources, `type` is the template’s
+ * `id`. The template’s `fields[].name` values describe the expected keys on `content`. The API also
+ * uses native `type` values (e.g. `directory`) and MIME types for binary uploads.
+ *
+ * @typeParam T — Shape of `content`; for template-backed resources, usually a record keyed by field names.
+ */
+interface Resource<T = unknown> {
     id: string;
     name: string;
+    /** Absolute path prefix for this resource; API normalizes with leading and trailing `/`. */
     location: string;
+    /** Workspace aggregate id this resource belongs to. */
     belongsTo: string;
+    /**
+     * Discriminator: resource template id, `directory`, or MIME type (file resources), depending on how the resource was created.
+     */
     type: string;
     createdBy: string;
     created: string;
     lastUpdated: string;
     content: T;
+    /** Present on API-backed media and other resources that support visibility rules. */
+    access?: 'public' | 'restricted';
+    /** When present (e.g. `['removed']`), the resource is treated as deleted in the event-sourced view. */
+    status?: string[];
 }
 
+/**
+ * Schema for a structured content type in a workspace. Imported via the workspace API and merged
+ * with built-in system templates when the API returns a workspace or template list.
+ *
+ * **Relation to {@link Resource}** — Creating a document resource requires `type` to equal this
+ * template’s `id`. Editors and clients use `fields` to render forms; `content` on the resource
+ * should align with those field names (by convention; enforcement may vary by API version).
+ */
 interface ResourceTemplate {
+    /** Stable identifier; becomes `Resource.type` for instances of this template. */
     id: string;
     name: string;
     description?: string;
     icon?: string;
+    /** Used by built-in templates for UI grouping; optional on custom imports. */
+    categoryName?: string;
     fields: Field[];
 }
 

package/build/types/src/Field.d.ts

@@ -1,9 +1,16 @@
+/**
+ * One input in a {@link ResourceTemplate}. The `name` is the key used in `Resource.content` for
+ * template-backed documents (alongside the editor’s input `type`, e.g. `text`, `textarea`, `richtext`, `select`).
+ */
 export interface Field {
+    /** Display label; UI may fall back to `name` when omitted. */
     label?: string;
+    /** Key stored in the resource’s `content` object. */
     name: string;
     type: string;
     description?: string;
     placeholder?: string;
     required?: boolean;
+    /** Allowed values for `select` / multiselect-style field types. */
     options?: string[];
 }

package/build/types/src/Resource.d.ts

@@ -1,11 +1,29 @@
-export interface Resource<T = any> {
+/**
+ * A resource is one item in a workspace tree (folder, structured document, media file, job record, etc.).
+ *
+ * **Relation to {@link ResourceTemplate}** — For document-like resources, `type` is the template’s
+ * `id`. The template’s `fields[].name` values describe the expected keys on `content`. The API also
+ * uses native `type` values (e.g. `directory`) and MIME types for binary uploads.
+ *
+ * @typeParam T — Shape of `content`; for template-backed resources, usually a record keyed by field names.
+ */
+export interface Resource<T = unknown> {
     id: string;
     name: string;
+    /** Absolute path prefix for this resource; API normalizes with leading and trailing `/`. */
     location: string;
+    /** Workspace aggregate id this resource belongs to. */
     belongsTo: string;
+    /**
+     * Discriminator: resource template id, `directory`, or MIME type (file resources), depending on how the resource was created.
+     */
     type: string;
     createdBy: string;
     created: string;
     lastUpdated: string;
     content: T;
+    /** Present on API-backed media and other resources that support visibility rules. */
+    access?: 'public' | 'restricted';
+    /** When present (e.g. `['removed']`), the resource is treated as deleted in the event-sourced view. */
+    status?: string[];
 }

package/build/types/src/ResourceTemplate.d.ts

@@ -1,8 +1,19 @@
 import { Field } from "./Field";
+/**
+ * Schema for a structured content type in a workspace. Imported via the workspace API and merged
+ * with built-in system templates when the API returns a workspace or template list.
+ *
+ * **Relation to {@link Resource}** — Creating a document resource requires `type` to equal this
+ * template’s `id`. Editors and clients use `fields` to render forms; `content` on the resource
+ * should align with those field names (by convention; enforcement may vary by API version).
+ */
 export interface ResourceTemplate {
+    /** Stable identifier; becomes `Resource.type` for instances of this template. */
     id: string;
     name: string;
     description?: string;
     icon?: string;
+    /** Used by built-in templates for UI grouping; optional on custom imports. */
+    categoryName?: string;
     fields: Field[];
 }

package/build/types/src/Theme.d.ts

@@ -77,34 +77,22 @@ export interface ColorPalette {
     } | undefined;
 }
 /**
- * Surface definitions - base surface colors and gradients.
+ * Surface definitions — flat preview strings (docs / tooling).
+ * Aligns with `surfaces` keys: base, primary, accent.
  */
 export interface SurfaceDefinitions {
-    primary?: CssValue;
-    secondary?: CssValue;
     base?: CssValue;
+    primary?: CssValue;
     accent?: CssValue;
-    'radial-gradient'?: CssValue;
-    'linear-gradient'?: CssValue;
-    decorated?: CssValue;
     [key: string]: CssValue | undefined;
 }
 /**
- * Surfaces - named surface variants for components.
- * Keys map to data-surface attribute values.
+ * Surfaces — named variants for `[data-surface="…"]`.
+ * Canonical set: base, primary, accent.
  */
 export interface SurfacesMap {
     base?: SurfaceVariant;
     primary?: SurfaceVariant;
-    secondary?: SurfaceVariant;
-    decorated?: SurfaceVariant;
-    'alt-primary'?: SurfaceVariant;
-    'alt-secondary'?: SurfaceVariant;
-    'radial-gradient'?: SurfaceVariant;
-    'linear-gradient'?: SurfaceVariant;
-    'alt-glass'?: SurfaceVariant;
-    info?: SurfaceVariant;
-    danger?: SurfaceVariant;
     accent?: SurfaceVariant;
     [key: string]: SurfaceVariant | undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ossy/types",
   "description": "Shared TypeScript types for all packages",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "url": "git://github.com/ossy-se/packages/types",
   "source": "src/index.ts",
   "module": "build/index.js",
@@ -26,5 +26,5 @@
     "/build",
     "README.md"
   ],
-  "gitHead": "5c689da5bbcfcdb39a81f7bed613a6559468464a"
+  "gitHead": "ce5a41d5ac2ca21450ec2f8a72ab98169ca433b5"
 }