@ankhorage/zora 17.0.0 → 18.0.0

package/src/features/form/{adapters/inbound/FormField.tsx → field/adapters/inbound/Field.tsx}

@@ -1,12 +1,12 @@
-import { Field } from '@ankhorage/surface';
+import { Field as SurfaceField } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
-import type { FormFieldProps } from '../../../../types/form';
-import { View } from '../../../layout/public';
-import { Text } from '../../../typography/public';
+import { withZoraThemeScope } from '../../../../../theme/withZoraThemeScope';
+import type { FieldProps } from '../../../../../types/form';
+import { View } from '../../../../layout/public';
+import { Text } from '../../../../typography/public';
 
-function FormFieldInner({
+function FieldInner({
   themeId: _themeId,
   mode: _mode,
   label,
@@ -15,9 +15,9 @@ function FormFieldInner({
   children,
   interactionPolicy: _interactionPolicy,
   ...props
-}: FormFieldProps) {
+}: FieldProps) {
   return (
-    <Field
+    <SurfaceField
       {...props}
       helperText={helperText}
       label={
@@ -34,9 +34,9 @@ function FormFieldInner({
       }
     >
       {children}
-    </Field>
+    </SurfaceField>
   );
 }
 
 /*** Groups one form control with its label, description, helper text, and field error. */
-export const FormField = withZoraThemeScope(FormFieldInner);
+export const Field = withZoraThemeScope(FieldInner);

package/src/features/form/{formFieldMeta.ts → field/meta.ts}

@@ -1,6 +1,7 @@
-import type { ZoraComponentMeta } from '../../metadata';
-export const formFieldMeta = {
-  name: 'FormField',
+import type { ZoraComponentMeta } from '../../../metadata';
+
+export const fieldMeta = {
+  name: 'Field',
   category: 'component',
   directManifestNode: true,
   allowedChildren: [
@@ -11,7 +12,7 @@ export const formFieldMeta = {
     'Select',
     'TextInput',
   ],
-  blueprint: { label: 'Form field', defaultProps: { label: 'Label' } },
+  blueprint: { label: 'Field', defaultProps: { label: 'Label' } },
   bindings: {
     props: {
       errorText: {

package/src/features/form/field/public.ts

@@ -0,0 +1 @@
+export { Field } from './adapters/inbound/Field';

package/src/features/form/formMeta.ts

@@ -3,7 +3,7 @@ export const formMeta = {
   name: 'Form',
   category: 'component',
   directManifestNode: true,
-  allowedChildren: ['FormError', 'FormField'],
+  allowedChildren: ['FormError', 'Field'],
   blueprint: {
     label: 'Form',
     defaultProps: { submitLabel: 'Submit', loading: false, disabled: false },

package/src/features/form/public.ts

@@ -1,10 +1,10 @@
 export type {
+  FieldProps,
   FormActionsProps,
   FormErrorProps,
   FormErrors,
   FormFieldConfig,
   FormFieldInputType,
-  FormFieldProps,
   FormProps,
   FormValidationErrors,
   FormValidationResult,
@@ -16,6 +16,6 @@ export type {
 export { Form } from './adapters/inbound/Form';
 export { FormActions } from './adapters/inbound/FormActions';
 export { FormError } from './adapters/inbound/FormError';
-export { FormField } from './adapters/inbound/FormField';
+export { Field } from './field/public';
 export { useFormController } from './useFormController';
 export { hasRequiredRule, validateField, validateFields, validateValue } from './utils/validation';

package/src/features/list/adapters/inbound/List.tsx

@@ -0,0 +1,77 @@
+import { List as SurfaceList } from '@ankhorage/surface';
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type {
+  ListItemProps,
+  ListItemsProps,
+  ListItemVariant,
+  ListProps,
+} from '../../../../types/list';
+import { Divider, View } from '../../../layout/public';
+import { resolveListSeparator } from '../../utils/resolveListSeparator';
+import { ListItem } from './ListItem';
+
+function resolveItemVariant({
+  item,
+  defaultVariant,
+}: {
+  item: ListItemProps;
+  defaultVariant: ListItemVariant;
+}): ListItemVariant {
+  return item.variant ?? defaultVariant;
+}
+
+function resolveItemCompact({
+  item,
+  compact,
+}: {
+  item: ListItemProps;
+  compact: boolean | undefined;
+}): boolean {
+  return item.compact ?? compact ?? false;
+}
+
+function ListItemsInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  items,
+  itemVariant = 'divider',
+  compact,
+}: ListItemsProps) {
+  return (
+    <SurfaceList testID={testID}>
+      {items.map((item, index) => {
+        const effectiveVariant = resolveItemVariant({ item, defaultVariant: itemVariant });
+        const separator = resolveListSeparator(effectiveVariant, index);
+        return (
+          <React.Fragment key={String(index)}>
+            {separator === 'divider' ? <Divider /> : null}
+            {separator === 'spacer' ? <View height="s" /> : null}
+            <ListItem
+              {...item}
+              compact={resolveItemCompact({ item, compact })}
+              variant={effectiveVariant}
+            />
+          </React.Fragment>
+        );
+      })}
+    </SurfaceList>
+  );
+}
+
+function ListInner(props: ListProps) {
+  if ('items' in props) return <ListItemsInner {...props} />;
+  const {
+    themeId: _themeId,
+    mode: _mode,
+    interactionPolicy: _interactionPolicy,
+    children,
+    testID,
+  } = props;
+  return <SurfaceList testID={testID}>{children}</SurfaceList>;
+}
+
+/*** List composition built on the Surface list boundary with ZORA item/separator policy. */
+export const List = withZoraThemeScope(ListInner);

package/src/features/list/adapters/inbound/ListItem.tsx

@@ -0,0 +1,89 @@
+import { ListItem as SurfaceListItem } from '@ankhorage/surface';
+import React from 'react';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ListItemProps, ListItemVariant } from '../../../../types/list';
+import { View } from '../../../layout/public';
+import { Text } from '../../../typography/public';
+
+function ListItemInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  interactionPolicy,
+  title,
+  description,
+  meta,
+  leading,
+  trailing,
+  action,
+  onPress,
+  selected = false,
+  disabled = false,
+  compact = false,
+  variant = 'divider',
+}: ListItemProps) {
+  const { theme } = useZoraTheme();
+  const trailingContent = renderTrailing(trailing, action);
+
+  return (
+    <View
+      bg={variant === 'card' ? theme.semantics.surface.raised : 'transparent'}
+      borderColor={
+        selected
+          ? theme.semantics.border.focus
+          : variant === 'card'
+            ? theme.semantics.border.default
+            : 'transparent'
+      }
+      borderWidth={variant === 'card' || selected ? 1 : 0}
+      overflow="hidden"
+      radius={resolveRadius(variant)}
+    >
+      <SurfaceListItem
+        compact={compact}
+        disabled={disabled}
+        interactionPolicy={interactionPolicy}
+        leading={leading}
+        onPress={action ? undefined : onPress}
+        selected={selected}
+        testID={testID}
+        trailing={trailingContent}
+      >
+        <View gap="xxs">
+          <Text variant="body" weight={selected ? 'semiBold' : 'medium'}>
+            {title}
+          </Text>
+          {description ? (
+            <Text emphasis="muted" variant="bodySmall">
+              {description}
+            </Text>
+          ) : null}
+          {meta ? (
+            <Text emphasis="subtle" variant="caption">
+              {meta}
+            </Text>
+          ) : null}
+        </View>
+      </SurfaceListItem>
+    </View>
+  );
+}
+
+function resolveRadius(variant: ListItemVariant) {
+  return variant === 'card' ? ('l' as const) : ('m' as const);
+}
+
+function renderTrailing(trailing: React.ReactNode, action: React.ReactNode) {
+  if (!trailing && !action) return undefined;
+  return (
+    <View align="center" direction="row" gap="s" wrap="nowrap">
+      {trailing}
+      {action}
+    </View>
+  );
+}
+
+/*** Opinionated list item built on the Surface list-item interaction and geometry boundary. */
+export const ListItem = withZoraThemeScope(ListItemInner);

package/src/{patterns/list → features/list/adapters/inbound}/ListSection.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { View } from '../../features/layout/public';
-import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
-import { SectionHeader } from '../section-header';
+import { SectionHeader } from '../../../../patterns/section-header';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ListSectionProps } from '../../../../types/list';
+import { View } from '../../../layout/public';
 import { List } from './List';
-import type { ListSectionProps } from './types';
 
 function ListSectionInner({
   themeId: _themeId,
@@ -17,7 +17,6 @@ function ListSectionInner({
   ...props
 }: ListSectionProps) {
   const hasHeader = title !== undefined;
-
   return (
     <View gap="s" testID={testID}>
       {hasHeader ? (
@@ -33,9 +32,5 @@ function ListSectionInner({
   );
 }
 
-/***
- * Section wrapper for lists with optional title and description.
- *
- 
- */
+/*** Section wrapper for lists with optional ZORA section-heading semantics. */
 export const ListSection = withZoraThemeScope(ListSectionInner);

package/src/{patterns → features}/list/meta.ts

@@ -1,6 +1,7 @@
 import type { ZoraComponentMeta } from '../../metadata';
 
-const LIST_NOTE = 'List pattern component; not represented as a manifest node in v1.';
+const LIST_NOTE =
+  'List feature component; collection authoring is represented through List metadata.';
 
 export const listMeta = {
   name: 'List',
@@ -11,8 +12,8 @@ export const listMeta = {
   props: {},
 } as const satisfies ZoraComponentMeta;
 
-export const listRowMeta = {
-  name: 'ListRow',
+export const listItemMeta = {
+  name: 'ListItem',
   category: 'pattern',
   directManifestNode: false,
   allowedChildren: [],
@@ -21,18 +22,10 @@ export const listRowMeta = {
     itemPress: {
       label: 'Item press',
       eventType: 'collection.itemPress',
-      description: 'Emitted when a collection item row is selected.',
+      description: 'Emitted when a collection item is selected.',
       payloadFields: [
-        {
-          path: 'payload.itemId',
-          type: 'string',
-          label: 'Item ID',
-        },
-        {
-          path: 'payload.item',
-          type: 'record',
-          label: 'Item',
-        },
+        { path: 'payload.itemId', type: 'string', label: 'Item ID' },
+        { path: 'payload.item', type: 'record', label: 'Item' },
       ],
     },
   },

package/src/features/list/public.ts

@@ -1,7 +1,18 @@
+export type {
+  ListChildrenProps,
+  ListItemProps,
+  ListItemsProps,
+  ListItemVariant,
+  ListProps,
+  ListSectionProps,
+} from '../../types/list';
 export type {
   ManifestListProps,
   ManifestListSection,
   ManifestSectionListProps,
 } from '../../types/manifest-list';
 export { FlatList } from './adapters/inbound/FlatList';
+export { List } from './adapters/inbound/List';
+export { ListItem } from './adapters/inbound/ListItem';
+export { ListSection } from './adapters/inbound/ListSection';
 export { SectionList } from './adapters/inbound/SectionList';

package/src/features/list/utils/resolveListSeparator.ts

@@ -0,0 +1,9 @@
+import type { ListItemVariant } from '../../../types/list';
+
+export type ListSeparatorKind = 'none' | 'divider' | 'spacer';
+
+/*** Resolves the separator preceding an item for the active list presentation. */
+export function resolveListSeparator(variant: ListItemVariant, index: number): ListSeparatorKind {
+  if (index === 0) return 'none';
+  return variant === 'divider' ? 'divider' : 'spacer';
+}

package/src/features/skeleton/adapters/inbound/SkeletonList.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { List, type ListRowProps } from '../../../../patterns/list';
 import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonListProps } from '../../../../types/skeleton';
+import { List, type ListItemProps } from '../../../list/public';
 import { Skeleton } from './Skeleton';
 import { SkeletonText } from './SkeletonText';
 
@@ -38,7 +38,7 @@ function SkeletonListInner({
   compact = false,
 }: SkeletonListProps) {
   const rowCount = clampRows(rows);
-  const items: ListRowProps[] = Array.from({ length: rowCount }).map(() => ({
+  const items: ListItemProps[] = Array.from({ length: rowCount }).map(() => ({
     compact,
     description: <SkeletonText lines={lines} />,
     leading: renderLeading({ avatar, media }),
@@ -46,7 +46,7 @@ function SkeletonListInner({
     variant,
   }));
 
-  return <List compact={compact} items={items} rowVariant={variant} testID={testID} />;
+  return <List compact={compact} items={items} itemVariant={variant} testID={testID} />;
 }
 
 /***

package/src/features/uploader/adapters/inbound/Uploader.tsx

@@ -4,7 +4,7 @@ import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { UploadAsset, UploaderProps, UploadType } from '../../../../types/upload';
 import { Button } from '../../../button/public';
 import { Dialog } from '../../../dialog/public';
-import { FormField } from '../../../form/public';
+import { Field } from '../../../form/public';
 import { Icon } from '../../../icon/public';
 import { Image } from '../../../image/public';
 import { View } from '../../../layout/public';
@@ -206,7 +206,7 @@ function UploaderInner({
 
   return (
     <>
-      <FormField
+      <Field
         description={description}
         disabled={disabled}
         errorText={effectiveError}
@@ -285,7 +285,7 @@ function UploaderInner({
             ) : null}
           </View>
         </View>
-      </FormField>
+      </Field>
 
       {canPreviewImage ? (
         <Dialog

package/src/index.ts

@@ -128,12 +128,12 @@ export {
   type CheckboxProps,
 } from './features/form/checkbox/public';
 export type {
+  FieldProps,
   FormActionsProps,
   FormErrorProps,
   FormErrors,
   FormFieldConfig,
   FormFieldInputType,
-  FormFieldProps,
   FormProps,
   FormValidationErrors,
   FormValidationResult,
@@ -143,10 +143,10 @@ export type {
   ValidationRule,
 } from './features/form/public';
 export {
+  Field,
   Form,
   FormActions,
   FormError,
-  FormField,
   hasRequiredRule,
   useFormController,
   validateField,
@@ -218,7 +218,16 @@ export type {
   ManifestListSection,
   ManifestSectionListProps,
 } from './features/list/public';
+export type {
+  ListChildrenProps,
+  ListItemProps,
+  ListItemsProps,
+  ListItemVariant,
+  ListProps,
+  ListSectionProps,
+} from './features/list/public';
 export { FlatList, SectionList } from './features/list/public';
+export { List, ListItem, ListSection } from './features/list/public';
 export { MissingElement, type MissingElementProps } from './features/missing-element/public';
 export { Pagination, type PaginationProps } from './features/pagination/public';
 export type { PaletteItemProps } from './features/palette-item/public';
@@ -361,14 +370,6 @@ export type { FilterBarProps } from './patterns/filter-bar';
 export { FilterBar } from './patterns/filter-bar';
 export type { InspectorFieldProps } from './patterns/inspector-field';
 export { InspectorField } from './patterns/inspector-field';
-export type {
-  ListChildrenProps,
-  ListItemsProps,
-  ListProps,
-  ListRowProps,
-  ListRowVariant,
-} from './patterns/list';
-export { List, ListRow, ListSection } from './patterns/list';
 export type {
   MessageBubbleAuthor,
   MessageBubbleAvatar,

package/src/metadata/bindableComponentMeta.ts

@@ -356,7 +356,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
     category: 'pattern',
     description: 'Renders a collection of list items.',
     directManifestNode: true,
-    allowedChildren: ['ListSection', 'ListRow'],
+    allowedChildren: ['ListSection', 'ListItem'],
     bindings: {
       props: {
         items: {

package/src/metadata/componentMeta.test.ts

@@ -63,7 +63,7 @@ describe('ZORA_COMPONENT_META event metadata', () => {
   });
 
   test('declares collection item metadata for list rows', () => {
-    const event = ZORA_COMPONENT_META.ListRow.events?.itemPress;
+    const event = ZORA_COMPONENT_META.ListItem.events?.itemPress;
     const eventType: ZoraComponentEventPayloadKind = event?.eventType ?? 'collection.itemPress';
 
     expect(eventType).toBe('collection.itemPress');
@@ -101,8 +101,8 @@ describe('ZORA_COMPONENT_META requirement metadata', () => {
 
 describe('ZORA_COMPONENT_META invariants', () => {
   test('keeps form nodes in their canonical hierarchy', () => {
-    expect(ZORA_COMPONENT_META.Form.allowedChildren).toEqual(['FormError', 'FormField']);
-    expect(ZORA_COMPONENT_META.FormField.allowedChildren).toEqual([
+    expect(ZORA_COMPONENT_META.Form.allowedChildren).toEqual(['FormError', 'Field']);
+    expect(ZORA_COMPONENT_META.Field.allowedChildren).toEqual([
       'Checkbox',
       'CheckboxGroup',
       'RadioGroup',
@@ -113,7 +113,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
     for (const [name, meta] of Object.entries(ZORA_COMPONENT_META)) {
       if (name === 'Form') continue;
       expect(meta.allowedChildren).not.toContain('FormError');
-      expect(meta.allowedChildren).not.toContain('FormField');
+      expect(meta.allowedChildren).not.toContain('Field');
     }
   });
 
@@ -204,7 +204,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'SectionList',
       'BottomSheet',
       'KeyboardAvoidingView',
-      'FormField',
+      'Field',
       'ButtonGroup',
       'Screen',
       'ScreenSection',

package/src/metadata/componentMeta.ts

@@ -29,9 +29,9 @@ import { datePickerMeta } from '../features/date-picker/datePickerMeta';
 import { dialogMeta } from '../features/dialog/dialogMeta';
 import { emptyStateMeta } from '../features/empty-state/emptyStateMeta';
 import { checkboxGroupMeta, checkboxMeta } from '../features/form/checkbox/checkboxMeta';
+import { fieldMeta } from '../features/form/field/meta';
 import { formActionsMeta } from '../features/form/formActionsMeta';
 import { formErrorMeta } from '../features/form/formErrorMeta';
-import { formFieldMeta } from '../features/form/formFieldMeta';
 import { formMeta } from '../features/form/formMeta';
 import { radioGroupMeta, radioMeta } from '../features/form/radio/radioMeta';
 import { searchInputMeta } from '../features/form/search-input/searchInputMeta';
@@ -50,6 +50,7 @@ import { screenSectionMeta } from '../features/layout/screenSectionMeta';
 import { scrollViewMeta } from '../features/layout/scrollViewMeta';
 import { viewMeta } from '../features/layout/viewMeta';
 import { flatListMeta } from '../features/list/flatListMeta';
+import { listItemMeta, listMeta, listSectionMeta } from '../features/list/meta';
 import { sectionListMeta } from '../features/list/sectionListMeta';
 import { missingElementMeta } from '../features/missing-element/missingElementMeta';
 import { paginationMeta } from '../features/pagination/paginationMeta';
@@ -80,7 +81,6 @@ import { collectionEditorMeta } from '../patterns/collection-editor/meta';
 import { confirmDialogMeta } from '../patterns/confirm-dialog/meta';
 import { filterBarMeta } from '../patterns/filter-bar/meta';
 import { inspectorFieldMeta } from '../patterns/inspector-field/meta';
-import { listMeta, listRowMeta, listSectionMeta } from '../patterns/list/meta';
 import { messageBubbleMeta } from '../patterns/message-bubble/meta';
 import { noticeMeta } from '../patterns/notice/meta';
 import { panelMeta } from '../patterns/panel/meta';
@@ -127,7 +127,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   Form: formMeta,
   FormActions: formActionsMeta,
   FormError: formErrorMeta,
-  FormField: formFieldMeta,
+  Field: fieldMeta,
   Gradient: gradientMeta,
   Heading: headingMeta,
   Icon: iconMeta,
@@ -182,7 +182,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   Hero: heroMeta,
   InspectorField: inspectorFieldMeta,
   List: listMeta,
-  ListRow: listRowMeta,
+  ListItem: listItemMeta,
   ListSection: listSectionMeta,
   MessageBubble: messageBubbleMeta,
   MissingElement: missingElementMeta,

package/src/patterns/inspector-field/InspectorField.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 
-import { FormField } from '../../features/form/public';
+import { Field } from '../../features/form/public';
 import { View } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { InspectorFieldProps } from './types';
@@ -15,12 +15,12 @@ function InspectorFieldInner({
   ...props
 }: InspectorFieldProps) {
   return (
-    <FormField {...props} label={label}>
+    <Field {...props} label={label}>
       <View direction="row" gap="s" align="center">
         <View flex={1}>{children}</View>
         {control ? <View>{control}</View> : null}
       </View>
-    </FormField>
+    </Field>
   );
 }
 

package/src/patterns/switch-field/SwitchField.tsx

@@ -1,8 +1,8 @@
 import { Switch } from '@ankhorage/surface';
 import React from 'react';
 
+import { ListItem } from '../../features/list/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
-import { ListRow } from '../list';
 import type { SwitchFieldProps } from './types';
 
 function SwitchFieldInner({
@@ -17,11 +17,7 @@ function SwitchFieldInner({
   interactionPolicy,
 }: SwitchFieldProps) {
   return (
-    <ListRow
-      title={label}
-      description={description}
-      disabled={disabled}
-      testID={testID}
+    <ListItem
       action={
         <Switch
           checked={value}
@@ -30,13 +26,17 @@ function SwitchFieldInner({
           onCheckedChange={onValueChange}
         />
       }
+      description={description}
+      disabled={disabled}
+      testID={testID}
+      title={label}
+      variant="card"
     />
   );
 }
 
 /***
- * Labeled switch field pattern built on `ListRow`.
+ * Labeled switch field pattern built on the card-style `ListItem` presentation.
  *
- 
  */
 export const SwitchField = withZoraThemeScope(SwitchFieldInner);

package/src/patterns/tree-view/TreeItem.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 
 import { IconButton } from '../../features/button/public';
 import { View } from '../../features/layout/public';
+import { ListItem } from '../../features/list/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
-import { ListRow } from '../list';
 import type { TreeItemNode, TreeItemRenderProps } from './types';
 
 interface TreeItemProps<TId extends string = string> extends ZoraBaseProps {
@@ -46,7 +46,7 @@ function TreeItemInner<TId extends string = string>({
     }
 
     return (
-      <ListRow
+      <ListItem
         title={node.label}
         action={
           <View direction="row" gap="xs" align="center">