nsh/base

nsh/base هي طبقة المكوّنات الأساسية في واجهة المستخدم للتطبيق: مكوّنات بلا تنسيق تتولى السلوك والحالة والتركيز وإمكانية الوصول على كل منصة. تقع بين العناصر الأولية (nsh وnsh/mobile وnsh/desktop) ومكتبة مكوّنات التطبيق نفسه، كما يقع gpui-base بين gpui ومكتبة منسّقة في GPUI Kit (راجع الوحدات). وهي توفّر عناصر تحكم (Button وLink وCheckbox وColorPicker مع ColorArea وColorSlider وColorField وColorSwatch وColorEyeDropper وNumberInput وRadio داخل RadioGroup وSlider وSwitch وTab في Tabs وToggle في ToggleGroup وSelect وCombobox وCalendar وTimeField وDatePicker)، ولوحات أوامر (Command)، وأشرطة عناصر تحكم (Toolbar مع ToolbarGroup وToolbarSeparator)، وأشرطة تمرير بمظهر التطبيق نفسه (Scrollbar)، ومناطق تتوسع وتنطوي (Collapsible، وAccordion مع AccordionItem وAccordionHeader وAccordionTrigger وAccordionPanel)، وشريط تقدّم (Progress)، ورموز الاستخدام لمرة واحدة (OtpInput)، وصفحات المجموعة (Pagination)، وعناصر تحوي عناصر (Tree)، والأجزاء التي تُبنى منها المخططات (Plot مع Line وArea وBar وRule وDot وCell وGrid وPie وArc، في nsh/base/plot)، ومساحات عمل يرتّبها المستخدم (عناصر ResizablePanel في ResizablePanelGroup، وتقسيمات DockArea ومجموعات علامات التبويب والمراسي)، وعروض شرائح دوّارة (Carousel وأجزاؤه)، ومستندات Markdown أو HTML (TextView)، ومحرر شيفرة (Editor)، والفروق بين النصوص (DiffView)، وجداول من الصفوف والأعمدة (Table وأجزاؤه، DataTable)، وحقول إدخال نصية (Input)، ونوافذ منبثقة تظهر فوق كل شيء (Popover وMenu وContextMenu مع MenuItem وMenuSeparator وSubmenu، Tooltip، Sheet)، وإشعارات مؤقتة (Toast في ToastStack، ودورة حياتها في ToastManager)، والتنقل (NavStack من NavPage تقوده الحالة التي تنشئها بـcreateNavStack، وDialog للمحتوى المعروض فوق كل شيء آخر)، ومربعات حوار التنبيه الخاصة بالنظام (AlertDialog). كما تحدد الصفحات ومربعات الحوار شريط الحالة (statusBar).

// Navigation: a stack of pages with header options, pushed and popped; in a
// wide window the inbox and the open message side by side (master–detail).
import { type JSX, mount, signal, Text, View } from "nsh";
import { createNavStack, NavPage, NavStack } from "nsh/base";
import { button, buttonText, focusRing, hoverFill, size, tint, ui, wide } from "./palette";

function Button(props: { title: string; variant?: "primary" | "secondary"; onPress: () => void }) {
  const kind = () => (props.variant !== "secondary" ? "primary" : "secondary");
  return (
    <View role="button" onPress={props.onPress} {...button(kind())}>
      <Text style={buttonText(kind())}>{props.title}</Text>
    </View>
  );
}

type Route = { name: "home" } | { name: "detail"; id: number };

const nav = createNavStack<Route>([{ name: "home" }]);

// The page's own header where NSH draws none (the web, the desktops); iOS and
// Android show the system's, from `title` and `headerRight`.
function Header(props: { title: string; right?: JSX.Element }) {
  return (
    <View style={{ backgroundColor: ui().page, borderBottomWidth: 1, borderBottomColor: ui().line }} class="h-12 flex-row items-center px-2">
      <View class="w-20 flex-row">
        <If when={nav.routes().length > 1}>
          <View role="button" accessibilityLabel="Back" onPress={() => nav.pop()} hoverStyle={hoverFill()} focusStyle={focusRing()} class="rounded-md px-2 py-1 active:opacity-60">
            <Text style={{ fontSize: 17, color: ui().accent }}>‹ Back</Text>
          </View>
        </If>
      </View>
      <Text style={{ numberOfLines: 1, fontSize: 17, fontWeight: "600", color: ui().text }} class="flex-1 text-center">
        {props.title}
      </Text>
      <View class="w-20 flex-row justify-end px-2">{props.right}</View>
    </View>
  );
}

// A page's content: a column as wide as a phone, centered in a wider window.
function Body(props: { children: JSX.Element }) {
  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 16, paddingTop: 24 }}>
      <View style={{ width: "100%", maxWidth: 480, alignSelf: "center", gap: 12 }}>{props.children}</View>
    </View>
  );
}

function Home() {
  const opened = signal(0);
  return (
    <NavPage title="Inbox" header={<Header title="Inbox" />}>
      <Body>
        <Text style={{ color: ui().muted }}>{`Opened ${opened()} messages`}</Text>
        <Button
          title="Open message 1"
          onPress={() => {
            opened.set(opened() + 1);
            nav.push({ name: "detail", id: 1 });
          }}
        />
        <Button title="Open message 2" variant="secondary" onPress={() => nav.push({ name: "detail", id: 2 })} />
      </Body>
    </NavPage>
  );
}

function Detail(props: { id: number }) {
  const starred = signal(false);
  const star = () => (
    <Text onPress={() => starred.set(!starred())} style={{ fontSize: 17, color: ui().accent }} hoverStyle={hoverFill()} focusStyle={focusRing()} activeStyle={{ opacity: 0.7 }}>
      {starred() ? "★" : "☆"}
    </Text>
  );
  return (
    <NavPage title={`Message ${props.id}`} headerRight={star()} header={<Header title={`Message ${props.id}`} right={star()} />}>
      <Body>
        <Text style={{ color: ui().text }}>{`The body of message ${props.id}.`}</Text>
        <Button title="Next message" onPress={() => nav.push({ name: "detail", id: props.id + 1 })} />
        <Button title="Back to the inbox" variant="secondary" onPress={() => nav.popToRoot()} />
      </Body>
    </NavPage>
  );
}

const messages = [1, 2, 3, 4, 5, 6];

/** A wide window: the inbox on the start side, the selected message beside it. */
function Inbox() {
  const selected = signal(1);
  const starred = signal<number[]>([]);
  const star = (id: number) => (
    <Text
      onPress={() => starred.set(starred().includes(id) ? starred().filter((s) => s !== id) : [...starred(), id])}
      style={{ fontSize: 17, color: ui().accent }}
      hoverStyle={hoverFill()}
      focusStyle={focusRing()}
      activeStyle={{ opacity: 0.7 }}
    >
      {starred().includes(id) ? "★" : "☆"}
    </Text>
  );
  return (
    <View style={{ flex: 1, flexDirection: "row", backgroundColor: ui().page }}>
      <View style={{ width: 320, borderRightWidth: 1, borderRightColor: ui().line }}>
        <Header title="Inbox" />
        <View style={{ padding: 8, gap: 2 }}>
          <Each of={messages}>
            {(id) => (
              <View
                role="button"
                onPress={() => selected.set(id())}
                hoverStyle={selected() === id() ? undefined : hoverFill()}
                style={{
                  height: size.row + 12,
                  paddingHorizontal: 12,
                  borderRadius: 8,
                  justifyContent: "center",
                  gap: 2,
                  backgroundColor: selected() === id() ? tint(ui().accent, 0.14) : "transparent",
                }}
                focusStyle={focusRing()}
                activeStyle={{ opacity: 0.7 }}
              >
                <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
                  <Text style={{ flex: 1, fontSize: size.label, fontWeight: "600", color: ui().text }}>{`Message ${id()}`}</Text>
                  <Text style={{ fontSize: 12, color: ui().accent }}>{starred().includes(id()) ? "★" : ""}</Text>
                </View>
                <Text style={{ numberOfLines: 1, fontSize: 12, color: ui().muted }}>{`The body of message ${id()}.`}</Text>
              </View>
            )}
          </Each>
        </View>
      </View>
      <View style={{ flex: 1, minWidth: 0 }}>
        <Header title={`Message ${selected()}`} right={star(selected())} />
        <View style={{ padding: 24, gap: 12 }}>
          <Text style={{ color: ui().text }}>{`The body of message ${selected()}.`}</Text>
          <Text style={{ fontSize: 13, color: ui().muted }}>Click a message on the left; on a phone it opens as a page of a NavStack.</Text>
          <Button title="Next message" onPress={() => selected.set(selected() === messages.length ? 1 : selected() + 1)} />
        </View>
      </View>
    </View>
  );
}

function App() {
  return (
    <>
      {() =>
        wide() ? (
          <Inbox />
        ) : (
          <NavStack state={nav} style={{ flex: 1 }}>
            {(route) => (route.name === "home" ? <Home /> : <Detail id={route.id} />)}
          </NavStack>
        )
      }
    </>
  );
}

mount(App);

تتضمن المجموعة الأساسية أيضًا Avatar وAvatarGroup: صور بحالة تحميل أصلية للصور، وصف يعرض أول limit من الصور الرمزية.

المظهر من شأن التطبيق: ما يوضع داخل صفحة أو مربع حوار أو ترويسة هو JSX خاص بك، مبني من العناصر الأولية بالأنماط وفئات Tailwind وسمتك، أو مكوّنات Rust من حزمتك الخاصة، أو مكتبة مكوّنات يبنيها المجتمع على nsh/base. كل مضيف يخدم nsh/base؛ وتستخدم تطبيقات Rust واجهة API نفسها من حزمة nsh-base (nsh_base::{button, dialog, …}).

use nsh_base::{
    MarkdownExtension, MarkdownOptions, accordion, accordion_header, accordion_item, accordion_panel, accordion_trigger,
    alert_dialog, button, carousel, carousel_content, carousel_item, carousel_next,
    carousel_pagination, carousel_pagination_item, carousel_previous, checkbox, color_area, color_field, color_picker,
    color_slider, color_swatch, dialog, diff_view, dock_area, editor, hover_card, link,
    calendar, combobox, command, date_picker, h_resizable, nav_page, nav_stack, radio, radio_group, resizable_panel, select, switch, tab, tabs, text_view, theme, time_field, toast, toast_stack, toggle, toggle_group, toolbar, toolbar_group, toolbar_separator, tree, v_resizable,
};

import {
  Accordion,
  AccordionHeader,
  AccordionItem,
  AccordionPanel,
  AccordionTrigger,
  AlertDialog,
  Avatar,
  AvatarGroup,
  Button,
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPagination,
  CarouselPaginationItem,
  CarouselPrevious,
  Checkbox,
  Collapsible,
  ColorArea,
  ColorEyeDropper,
  ColorField,
  ColorPicker,
  ColorSlider,
  ColorSwatch,
  ContextMenu,
  createNavStack,
  DataTable,
  Dialog,
  DiffView,
  DockArea,
  Editor,
  HoverCard,
  Link,
  Menu,
  OtpInput,
  Pagination,
  Progress,
  MenuItem,
  MenuSeparator,
  NavPage,
  NavStack,
  Popover,
  Radio,
  RadioGroup,
  ResizablePanel,
  ResizablePanelGroup,
  Scrollbar,
  Select,
  Combobox,
  Command,
  Calendar,
  TimeField,
  DatePicker,
  Sheet,
  NumberInput,
  Slider,
  Submenu,
  Switch,
  Tab,
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
  Tabs,
  TextView,
  Toast,
  ToastManager,
  ToastStack,
  Toggle,
  ToggleGroup,
  Toolbar,
  ToolbarGroup,
  ToolbarSeparator,
  Tree,
  Tooltip,
} from "nsh/base";
import type {
  AccordionHeaderProps,
  AccordionItemProps,
  AccordionPanelProps,
  AccordionProps,
  AccordionTriggerProps,
  AlertDialogAction,
  AlertDialogOptions,
  AlertDialogPresentation,
  AlertDialogResult,
  AlertDialogRole,
  AvatarGroupProps,
  AvatarProps,
  AvatarStatus,
  ButtonProps,
  CarouselContentProps,
  CarouselControlProps,
  CarouselItemProps,
  CarouselPaginationItemProps,
  CarouselPaginationProps,
  CarouselProps,
  CheckboxProps,
  CollapsibleProps,
  ColorAreaProps,
  ColorChannel,
  ColorFieldProps,
  ColorFormat,
  ColorPickerProps,
  ColorSliderProps,
  ColorSpace,
  ColorSwatchProps,
  DialogChangeReason,
  DataTableColumn,
  DataTableProps,
  DataTableRef,
  DataTableSelection,
  DataTableSort,
  DialogProps,
  DiffAnnotation,
  DiffFile,
  DiffHunk,
  DiffLineRange,
  DiffSeparator,
  DiffStats,
  DiffViewProps,
  DiffViewRef,
  DockAreaLayout,
  DockNode,
  DockRegion,
  EditorDecoration,
  EditorDiagnostic,
  EditorProps,
  EditorRef,
  EditorReplaceAll,
  EditorSearch,
  EditorSearchResult,
  EditorSelection,
  Edges,
  HeaderStyle,
  LinkOpenWith,
  LinkProps,
  NavPageProps,
  NavStackProps,
  NavStackState,
  OtpInputProps,
  PaginationItemState,
  PaginationProps,
  ProgressProps,
  StatusBar,
  RadioGroupProps,
  RadioProps,
  NumberInputProps,
  SelectEntry,
  SelectGroup,
  SelectItem,
  SelectProps,
  ComboboxProps,
  CommandEntry,
  CommandGroup,
  CommandItem,
  CommandProps,
  CalendarProps,
  TimeFieldProps,
  DatePickerProps,
  ScrollbarEntrance,
  ScrollbarLook,
  ScrollbarMode,
  ScrollbarMotion,
  ScrollbarProps,
  ScrollbarTheme,
  SliderProps,
  SliderScale,
  SliderValue,
  StatusBarForeground,
  SwitchProps,
  TabProps,
  TabsProps,
  TextViewProps,
  TextViewDocument,
  MarkdownExtension,
  MarkdownOptions,
  ToastEntry,
  ToastMotion,
  ToastOptions,
  ToastProps,
  ToastStackProps,
  ToastTransitionStatus,
  ToggleGroupProps,
  ToggleProps,
  ToolbarProps,
  TreeEntry,
  TreeItem,
  TreeProps,
} from "nsh/base";

هذه الصفحة هي فهرس الوحدة: لكل مكوّن صفحة عنصر فيها أمثلته وخصائصه وملاحظات المنصات. وللاطلاع على الشروحات، راجع دليل التنقل والنماذج ولوحة المفاتيح.

في Rust، يقرأ theme() سمة التطبيق على شكل رموز تصميم (theme().primary، theme().radius)، وهي الرموز نفسها التي تستخدمها فئات السمة في TSX.

#عناصر التحكم

#Button

هدف ضغط يتولى سلوكه وليس له مظهر: الضغطات وحالتا التعطيل والتحديد ودوره لقارئات الشاشة. مظهره هو class وstyle الخاصان بالتطبيق مع متغيّرات الحالة، ومحتواه هو عناصره الفرعية. راجع Button.

#Link

هدف ضغط ينقل إلى مكان ما وليس له مظهر: الضغطات، ومفتاحا Return وSpace أثناء امتلاكه تركيز لوحة المفاتيح، وحالة التعطيل، ودور الرابط لقارئات الشاشة، والصفحة الحالية في التنقل (current). وhref هو وجهته التي لا تُعرض أبدًا: يبلّغ الضغط عنها (onOpen)، ثم يفتح صفحة ويب أو رابط تطبيق آخر خارج التطبيق، أو يترك الفتح، مع openWith="app"، لمسارات التطبيق الخاصة. راجع Link.

#Checkbox

عنصر تحكم محدد أو غير محدد أو غير محسوم يتولى سلوكه وليس له مظهر: الضغطات، والتفعيل بلوحة المفاتيح، وحالة التعطيل، ودور خانة الاختيار وقيمتها لقارئات الشاشة (مختلطة أثناء عدم الحسم)، مع كون القيمة مملوكة للتطبيق (checked، indeterminate، onChange). ينسّق التطبيق خانة الاختيار ومؤشرها، وتتبع فئات checked: وindeterminate: وdisabled: الخاصة بالمؤشر خانة الاختيار، ويضع التطبيق علامته الخاصة في المؤشر (indicator). راجع Checkbox.

#Radio and RadioGroup

خيار واحد من مجموعة يختار المستخدم منها واحدًا بالضبط، والمجموعة المحيطة بها. يتولى الراديو سلوكه وليس له مظهر: الضغطات، والتفعيل بلوحة المفاتيح، وحالة التعطيل، ودور الراديو وحالة تحديده لقارئات الشاشة. أما المجموعة فهي مجموعة الراديو التي تعلنها قارئات الشاشة ولا تحمل قيمة: يخبر التطبيق كل راديو بما إذا كان محددًا (checked)، ويطلب الضغط على راديو غير محدد تحديده (onChange). مؤشر التطبيق وتسميته هما العنصران الفرعيان للراديو، وتتبعه فئات group-checked: الخاصة بهما. راجع Radio.

#Switch

عنصر تحكم للتشغيل / الإيقاف يتولى سلوكه وليس له مظهر: الضغطات، والتفعيل بلوحة المفاتيح، وحالة التعطيل، ودور المفتاح وقيمته لقارئات الشاشة، مع كون القيمة مملوكة للتطبيق (checked، onChange). ينسّق التطبيق المفتاح ومساره ومقبضه، وتتبع فئات checked: وdisabled: المفتاحَ. راجع Switch.

#Tab and Tabs

علامات التبويب في قائمة علامات التبويب والقائمة المحيطة بها. تتولى علامة التبويب سلوكها وليس لها مظهر: الضغطات، والتفعيل بلوحة المفاتيح، وحالة التعطيل، ودور علامة التبويب وحالة تحديدها لقارئات الشاشة. والقائمة هي قائمة علامات التبويب التي تعلنها قارئات الشاشة ولا تحمل قيمة: يخبر التطبيق كل علامة بما إذا كانت محددة (selected)، ويستمع إلى الضغطات (onPress)، ويعرض بنفسه محتوى القسم المحدد. تسمية التطبيق هي العنصر الفرعي لعلامة التبويب، وتتبعها فئات group-selected: الخاصة بها. ومؤشر القائمة (indicatorClass، indicatorStyle)، وهو خط سفلي أو حبّة ينسّقها التطبيق، يستقر على علامة التبويب المحددة وينتقل إلى التالية أصليًا بحركة نابضية. راجع Tabs.

#Carousel

شرائح تُعرض واحدة في كل مرة (صور منتج، شاشة تعريفية، لافتة، صف من البطاقات). المحتوى عبارة عن scroll view أصلي يلتقط بدايات الشرائح، فيحرّكها الإصبع وعجلة الفأرة ولوحة اللمس في الإطار نفسه الذي يتحرك فيه المؤشر. وعندما يستقر، يبلغ الـ carousel عن الشريحة المعروضة عبر onChange. ويحرّكه بشكل أصلي كل من السابق والتالي (CarouselPrevious، CarouselNext) والترقيم (عدة CarouselPaginationItem داخل CarouselPagination، مع مؤشر ينتقل بحركة نابضية إلى الشريحة المعروضة) ومفاتيح الأسهم، مع الالتفاف عند الطرفين بسلاسة بواسطة looping. الشريحة المعروضة هي index الخاصة بالتطبيق، ويقدّمها مؤقّت التطبيق نفسه للشرائح التي تنتقل من تلقاء نفسها (onDragStart / onDragEnd، onFocus / onBlur تحدد متى ينتظر)؛ أما المظهر وكل التسميات فمن مسؤولية التطبيق. انظر Carousel.

#Toggle and ToggleGroup

زر يكون مفعّلًا أو غير مفعّل (غامق، مفضلة، خيار عرض)، وشريط أدوات من هذه الأزرار. يتولى الـ toggle سلوكه بنفسه وليس له مظهر: الضغطات، والتفعيل بلوحة المفاتيح، وحالة التعطيل، ودور الزر مع حالة الضغط لقارئات الشاشة. أما المجموعة فهي شريط الأدوات الذي تعلن عنه قارئات الشاشة، وتمثّل محطة واحدة في تركيز لوحة المفاتيح تنقل مفاتيح الأسهم فيها بين الـ toggles دون ضغطها، ولا تحمل أي قيمة: يخبر التطبيق كل toggle بما إذا كان مضغوطًا (pressed)، ويسمع القيمة التي يطلبها (onChange)، ويُبقي أي عدد منها مضغوطًا أو واحدًا فقط. ويعطّل disabled على المجموعة كل toggle فيها. وأيقونة التطبيق أو تسميته هي children الخاصة بالـ toggle، وتتبعها فئات group-aria-pressed:. انظر Toggle.

#Toolbar, ToolbarGroup and ToolbarSeparator

شريط من عناصر التحكم: تنسيق محرر نصوص، أو أزرار التشغيل في مشغّل وسائط، أو لوحة أدوات عمودية. الـ toolbar هو ما تعلن عنه قارئات الشاشة (ويُسمّى بواسطة accessibilityLabel)، وهو محطة واحدة في تركيز لوحة المفاتيح فوق Button وToggle وLink التي بداخله: يدخل Tab عند العنصر الذي غادره آخر مرة، وتتحرك مفاتيح الأسهم الخاصة بـ axis على امتداده، ويقفز Home وEnd إلى طرفيه، دون ضغط أي شيء. وToolbarGroup هي مجموعة مسمّاة من العناصر المترابطة (التراجع والإعادة، أو المحاذاة)، وToggleGroup داخل toolbar هي إحدى مجموعاته، وتكون أزرار toggle فيها عناصر الـ toolbar. وToolbarSeparator هو خط يرسمه التطبيق بين المجموعات. ويعطّل disabled على الـ toolbar أو على مجموعة كل عنصر فيها. لا يحمل الـ toolbar أي قيمة وليس له مظهر: يحتفظ كل عنصر تحكم بحالته، ويصمم التطبيق الشريط ومجموعاته وفواصله. انظر Toolbar.

#Select

اختيار قيمة واحدة من قائمة عناصر تُعطى كبيانات (items: لكل عنصر قيمة وعنوان، وقد يكون معطّلًا أو ضمن قسم)، دون مظهر. يفتح زرّ التطبيق القائمة: نافذة منبثقة عند الزر على أجهزة سطح المكتب، وورقة (sheet) من الأسفل على الهواتف والأجهزة اللوحية. يتولى الـ select لوحة المفاتيح (Up وDown وHome وEnd وPage Up وPage Down والإكمال بالكتابة وReturn وEscape)، والبحث (searchable)، والصف المميّز (focus: على itemClass؛ ويتلقى renderItem ماهية العنصر، لا حالته أبدًا)، وأدوار combobox وlistbox وoption لقارئات الشاشة. ويملك التطبيق القيمة (value، onChange) أو يتركها للـ select (defaultValue)، ويصمم كل جزء أو يرسم الصفوف. انظر Select.

#Combobox

قيم تُختار من قائمة عناصر، مثل قائمة select، وتُصفّى بالكتابة في حقل إدخال الـ combobox، دون مظهر: قيمة واحدة، أو عدة قيم مع multiple، وعندها يبدّل الاختيار حالة العنصر بينما تبقى القائمة مفتوحة. القيمة مصفوفة يملكها التطبيق (value، onChange) أو يتركها للـ combobox (defaultValue)؛ ويخبر onConfirm بها عند إغلاق القائمة. ويمكن أن يملك التطبيق الاستعلام (query، onQueryChange)، ويظهر تذييل تحت الصفوف، ويفرّغ زر المسح القيمة. انظر Combobox.

#Calendar

تاريخ، أو نطاق من التواريخ مع range، يُختار من أشهر مؤلفة من أيام، دون مظهر. يُعرض شهر واحد أو عدة أشهر (numberOfMonths) جنبًا إلى جنب؛ وتنقلها الترويسة وتفتح عرضًا للأشهر أو صفحة للسنوات. القيمة تاريخ بصيغة ISO ("2026-10-28") أو [start, end] يملكه التطبيق (value، onChange) أو يتركه للـ calendar (defaultValue)؛ ويمنع disabledMatcher اختيار أيام معينة، وتتلقى الأيام لوحة المفاتيح كمحطة واحدة لمفتاح Tab. يصمم التطبيق الأجزاء ويرسم العناصر (renderItem، مع إعطائه ماهية العنصر؛ وحالاته هي فئاته، وأيام النطاق selected: مع data-range-start: وdata-range-middle: وdata-range-end:). انظر Calendar.

#TimeField

وقت من اليوم يُحرَّر قطاعًا بعد قطاع، دون مظهر: الساعة والدقيقة والثانية (precision) وAM/PM (hourCycle="h12")، بالزيادة والنقصان أو بالكتابة أو بلوحة أرقام الهاتف. القيمة هي "HH:MM" ("HH:MM:SS") بنظام 24 ساعة، يملكها التطبيق (value، onChange) أو الحقل نفسه (defaultValue). انظر TimeField.

#DatePicker

تاريخ يُختار من calendar يُفتح من زرّ التطبيق، كما تُفتح قائمة select: نافذة منبثقة على أجهزة سطح المكتب، وورقة على الهواتف. القيمة بصيغ مدخلات HTML: تاريخ ISO، أو [start, end] مع range، أو تاريخ ووقت مع timePrecision (حقل وقت تحت calendar)، يملكها التطبيق (value، onChange) أو الـ picker نفسه (defaultValue). تضبط القيم المسبقة (presets) القيمة، ويمسحها زر المسح، وتُمرَّر كل خاصية من خاصيات Calendar. انظر DatePicker.

#Collapsible

منطقة يتمدد محتواها وينطوي، دون مظهر: تظهر children الخاصة بها دائمًا (ملخص، الزر المحفّز)، ويظهر content بعدها عندما يكون open. يملك التطبيق open والزر الذي يقلبها، ويُعلِم قارئات الشاشة بحالة التمدد هناك. يُنشأ المحتوى مرة واحدة ويبقى أثناء الانطواء، فيحتفظ ما بداخله بحالته. ومع reveal يُفتح ويُغلق بارتفاع نابضي، بشكل أصلي. انظر Collapsible.

#Accordion

أقسام مكدّسة تتمدد وتنطوي تحت عناوينها، دون مظهر: Accordion من AccordionItem، كل منها AccordionHeader يحيط بـ AccordionTrigger وAccordionPanel. يملك التطبيق value، وهي قيم العناصر المفتوحة، ويضبط القيمة الوحيدة التي يبلغ عنها onChange عند الضغط على زر محفّز: عنصر واحد في كل مرة، أو عدة عناصر مع multiple. تسمع قارئات الشاشة مجموعة من العناوين تبيّن أزرارها ما إذا كان عنصرها ممدّدًا، وكل لوحة مفتوحة كمنطقة (region). ومع reveal تُفتح اللوحة وتُغلق بارتفاع نابضي، بشكل أصلي؛ ومع keepMounted يبقى محتواها في الشجرة أثناء الإغلاق. انظر Accordion.

#Avatar

صورة شخص، دون مظهر: البديل (الأحرف الأولى من name، أو fallback الخاص بالتطبيق) والصورة فوقه، شفافة حتى تُحمَّل، وكلاهما بحجم الـ avatar نفسه، ثم children الخاصة بالتطبيق (نقطة الحضور). تغيّر أحداث التحميل والخطأ في الصورة نفسها حالتها بشكل أصلي (onStatusChange)، ويُبقي fallbackDelay البديل في الخلف أثناء تحميل الصورة. تسمع قارئات الشاشة صورة موسومة بالاسم. ويعرض AvatarGroup أول limit من الـ avatars، ولا ينشئ views للبقية، ويعرض overflow عندما يكون total أكبر. انظر Avatar.

#Progress

شريط تقدّم خطي، دون مظهر: مسار يحتوي على مؤشر، عرض المؤشر value بالمئة من عرض المسار. يملك التطبيق value (من 0 إلى 100) وindeterminate؛ وتحصل قارئات الشاشة على دور شريط التقدّم والنطاق والقيمة، ولا قيمة أثناء الحالة غير المحدّدة، حيث يكون عرض المؤشر وحركته من شأن التطبيق. انظر Progress.

#NumberInput

رقم يُكتب في حقل أو يُزاد وينقص بالخطوات، دون مظهر: الحقل (Input)، وزر النقصان قبله وزر الزيادة بعده (أو كلاهما في عمود على اليمين، controlsRight). يملك التطبيق value (رقمًا أو null؛ أو يحتفظ الـ input بقيمته الخاصة من defaultValue) ويسمع onChange مع الرقم الذي يقرؤه الحقل. يقبل الحقل رقمًا أو النص في طريقه إلى أن يصبح رقمًا، بما في ذلك أرقام وإشارات لوحات المفاتيح الأخرى؛ وتغيّر الأزرار ومفتاحا Up / Down ومفتاحا Page Up / Page Down القيمة بمقدار step، مع الحفاظ على الكسور العشرية، حتى min وmax، ويُخضع مغادرة الحقل القيمة المكتوبة لهما. والحقل عنصر spin button لقارئات الشاشة، وتغيّره أوامر الزيادة والنقصان فيه. انظر NumberInput.

#Slider

قيمة، أو نطاق من قيمتين، تُختار على امتداد مسار، دون مظهر: مسار يستقبل الضغطات والسحب، والمؤشر بداخله الذي تُعيَّن عليه القيم، والنطاق وإبهام (thumb) واحد لكل قيمة عليه. يملك التطبيق value (رقمًا أو [start, end]؛ أو يحتفظ الـ slider بقيمته الخاصة من defaultValue) ويسمع onChange لكل قيمة جديدة، مقرَّبة إلى step بدءًا من min، وonChangeEnd مرة واحدة لكل تغيير؛ ويوزّع scale القيم خطيًا أو بحسب رتب الحجم، ويرتّب axis المسار أفقيًا أو عموديًا. كل إبهام عنصر قابل للضبط لقارئات الشاشة بقيمته الخاصة، وهو محطة في تركيز لوحة المفاتيح، ويتحرك بمفاتيح slider في WAI-ARIA. انظر Slider.

#Scrollbar

شريط تمرير بمظهر التطبيق الخاص لـ scroll view أو لقائمة، يوضع حيث يريد التطبيق، دون مظهر: مسار (class الخاص بالشريط) وإبهام فيه (thumbClass). يسمّي الـ scroll view الخاص به (scroll، ref الخاص به) ويتبع إزاحته ومحتواه ونافذة العرض؛ ويمرّر سحب الإبهام المحتوى، ويحرّك الضغط على المسار منتصف الإبهام إلى هناك. يُظهره mode أثناء تمرير المحتوى (حتى motion.idle بعد ذلك)، أو أثناء وجود المؤشر فوق الشريط، أو دائمًا؛ ويجعله axis أفقيًا. ويعطي Scrollbar.setTheme كل scroll view وقائمة شريطًا بمظهر التطبيق فوق نافذة عرضه، دون شريط يُوضع يدويًا، ويمكن لأي view أن يأخذ سمة خاصة به عبر خاصية scrollbar. انظر Scrollbar.

#ColorPicker

منتقي ألوان دون مظهر: يحمل الجذر اللون وتعرضه الأجزاء بداخله وتغيّره، ويرتّبها التطبيق. ColorArea هو التشبّع والسطوع في HSB، وColorSlider أي قناة من RGB أو HSL أو HSB أو OKLCH أو القناة الشفافة alpha (أفقيًا أو عموديًا)، وColorField اللون بأي صيغة CSS أو رقم قناة، وColorSwatch لون مسبق يختاره الضغط أو معاينة للون، وColorEyeDropper زر يلتقط لونًا من الشاشة (macOS، الويب). يملك التطبيق value (أو يحتفظ المنتقي بقيمته الخاصة من defaultValue) ويسمع onChange وonChangeEnd مع اللون ونصه كما يكتبه format؛ ويحتفظ المنتقي بقنوات كل فضاء لوني كما ضبطها المستخدم. والإبهامات عناصر قابلة للضبط لقارئات الشاشة ومحطات في تركيز لوحة المفاتيح. انظر ColorPicker.

#OtpInput

رمز رقمي لمرة واحدة بطول ثابت، دون مظهر: حقل نصي أصلي واحد فوق الخلايا يستقبل لوحة المفاتيح، فالكتابة واللصق ولوحة الأرقام والملء التلقائي للرمز من النظام كلها من عمل المنصة، وتجد قارئات الشاشة حقلًا نصيًا واحدًا. لا تدخل إلا الأرقام، حتى length؛ ويزيل Backspace آخر رقم. يملك التطبيق value (أو يعطي defaultValue) ويسمع onChange وonComplete؛ ويصمم الخلايا (focus: على الخلية التي تستقبل الرقم التالي، وdata-filled: على الخلايا التي تحمل رقمًا) ومجموعاتها والمؤشر. انظر OtpInput.

#Pagination

صفحات مجموعة يُنتقل بينها، معلم تنقّل (navigation landmark) دون مظهر: السابق، والصفحة الأولى والأخيرة، والصفحة الحالية مع جاراتها (visiblePages)، وعلامة حذف لكل مقطع محذوف، وchildren الخاصة بالتطبيق، والتالي؛ ويُبقي compact السابق وchildren والتالي. يملك التطبيق page ويسمع onChange({ page })؛ والصفحة الحالية هي selected: والصفحة الحالية لقارئات الشاشة. يصمم التطبيق العناصر (itemClass) أو يرسمها (renderItem). انظر Pagination.

#Command

لوحة أوامر: حقل بحث فوق أوامر التطبيق (items: id، وlabel، وkeywords، وgroup، وshortcut لعرضه، وdisabled، وchecked)، تُصفّى أصليًا أثناء كتابة المستخدم (تحمل التسمية أو الكلمة المفتاحية الاستعلام، مع تجاهل حالة الأحرف؛ وتُحذف الأقسام التي لا تطابق)، في قائمة افتراضية (virtualized) لا تنشئ إلا الصفوف الظاهرة. يحرّك Up وDown التمييز، ويختار Return أو الضغط (onSelect({ id }))، ويمسح Escape الاستعلام ثم يبلّغ عن onCancel، حيث يغلق التطبيق Dialog المحيط به. الاستعلام يملكه التطبيق (query، onQueryChange) أو الحقل نفسه؛ ومع filterable={false} وloading يجيب التطبيق عنه من خادم. يصمم التطبيق كل جزء (itemClass مع focus: للتمييز، checked:، disabled:) ويرسم الصفوف (renderItem، مع إعطائه الاختصار كما يظهر هنا). انظر Command.

#Tree

عناصر تحتوي على عناصر: ملفات مشروع، شريط جانبي للإعدادات، مخطط تفصيلي. items بيانات (TreeItem: id، وlabel، وchildren، وdisabled)، والصفوف افتراضية (virtualized): لا يُنشأ منها إلا الظاهر، ولا يُنشأ أبناء العنصر المنطوي أبدًا، فتبقى شجرة من آلاف العناصر سريعة. يملك التطبيق معرّفات العناصر الممدّدة والعنصر المحدد (expanded، selected، مع onExpandedChange وonSelectedChange) أو تحتفظ الشجرة بحالتها الخاصة (defaultExpanded، defaultSelected). يحدد الضغط صفًا ويمدّد المجلد أو ينطويه؛ والشجرة محطة واحدة في تركيز لوحة المفاتيح، تحرّك مفاتيح الأسهم فيها التحديد (يمدّد Right وينطوي Left، ويدخلان المجلد ويغادرانه)، مع Home وEnd وReturn وSpace والإكمال بالكتابة. يصمم التطبيق الصفوف (itemClass مع selected:، aria-expanded:، focus:) ويرسمها (renderItem، مع إعطائه depth لكل عنصر). انظر Tree.

#Plot (nsh/base/plot)

الأجزاء التي تُبنى منها المخططات، كما في gpui-base الخاص بـ plot، في وحدة مستقلة: import { Plot, Line, Area, Bar, Grid, Pie, Arc, Sankey, Treemap } from "nsh/base/plot". A Plot holds the app’s rows (data, generic over their type, so x and y (x وy مفاتيح مفحوصة أو دوال لصف من الصفوف)، ومقاييس point أو linear أو band لمحاورها، والصف الواقع تحت المؤشر (onHoverChange) وحركته (motion: الظهور، وتلاشي التمرير وانزلاقه). ترسم علاماتها محليًا انطلاقًا من الصفوف، دون أي JS لكل نقطة، وتُطلى بخصائص طلاء SVG (stroke-*، fill-*)، مع currentColor حيث لا يوجد تحديد؛ ويعرض Area أو Bar خلفية (تدرجًا لونيًا، bg-linear-*) داخل أشكاله. تقف الأعمدة في نطاقات مقياس band، جنبًا إلى جنب أو متراصة في stack، وتنمو عند ظهور المخطط وتتلاشى بعيدًا عن الصف الواقع تحت المؤشر، مع جزء label عند طرف كل عمود. أما الخط المتقاطع للتمرير، والنقاط (لكل علامة نقطتها الخاصة مع hoverDotClass)، والتلميح (tooltipPlacement، ويبقى داخل المخطط) فهي أجزاء ينسّقها التطبيق ويملؤها، وتتحرك محليًا؛ وتسميات المحاور هي عناصر التطبيق نفسه. يقسّم Pie الدورة إلى شريحة لكل صف (حلقة دائرية مع innerRadius)، وتُطلى كل شريحة بفئاتها الخاصة (sliceClass، دالة لصفها)، ويرسم Arc قطاعًا واحدًا بين زاويتين (مسار مقياس القياس وقيمته)؛ وفوق المخطط الدائري يبلّغ المخطط عن الشريحة الواقعة تحت المؤشر، فترتفع (hoverLift) بينما تتلاشى الأخرى (hoverDim). يرسم Sankey التدفقات بين الصفوف (links)، ويرتبها بالطريقة التي يرتبها بها d3-sankey، ويُطلى كل عقدة وشريط بفئاته الخاصة، وتحمل عقده تسميات وتستجيب للتمرير وتنتقل إلى تدفقات جديدة. يرصف Treemap الصفوف على هيئة تسلسل هرمي من المستطيلات المتداخلة (id، parent)، ومساحة كل ورقة هي value، وتُلوَّن بحسب الفئة أو على امتداد تدرج من colorScale الخاص بالمخطط، وتظهر تسمياتها حيث تتسع لها المساحة. راجع Plot.

#مساحات العمل

#ResizablePanelGroup و ResizablePanel

لوحات جنبًا إلى جنب أو متراصة، بينها مقبض بين كل لوحتين يسحبه المستخدم لتقاسم المساحة. تتولى المجموعة السحب، الذي يجري محليًا، وحدود كل لوحة (minSize، maxSize) ومؤشر تغيير الحجم؛ أما الأحجام فهي للتطبيق (size، ويُبلَّغ عنها عبر onResize)، وكذلك مظهر المقابض ومحتوى اللوحات. راجع Resizable.

#DockArea

مساحة عمل قابلة للإرساء: لوحات في مجموعات تبويب، ومجموعات مقسّمة جنبًا إلى جنب أو متراصة، وأرصفة على الحواف اليسرى واليمنى والسفلية. التخطيط بيانات يملكها التطبيق (layout، ويُبلَّغ عنها عبر onLayoutChange)؛ وتتولى المنطقة سحب التبويبات وإفلاتها، وتغيير الحجم، والأرصفة، والتكبير، والقفل، وتحافظ على محتوى كل لوحة أثناء انتقالها، وتعرض التخطيط نفسه بأدراج وورقة سفلية عندما تكون المساحة ضيقة. أما التبويبات والمقابض ومؤشر الإفلات ومحتوى اللوحات فهي للتطبيق. راجع Dock.

#المستندات

#TextView

يعرض TextView مستندًا بصيغة Markdown أو HTML أو كتل يبنيها التطبيق، ويرسمه بعناصر Text وطرق عرض: عناوين وقوائم وشيفرة وجداول وصور ومعادلات وحواشٍ سفلية وصيغة التطبيق الخاصة. وهو مصمم لردود الدردشة بالذكاء الاصطناعي التي تصل تدفقًا، بطباعة مخصصة للقراءة بألوان السمة يعيد التطبيق تنسيقها جزءًا جزءًا، ودوال عرض تضع محتوى التطبيق في مكانه. راجع TextView.

#الشيفرة

#Editor

Editor محرر شيفرة لأكثر من خمسين لغة: تلوين الصياغة، وأرقام الأسطر، وعدة مؤشرات إدراج، والطي، والالتفاف التلقائي، والبحث والاستبدال، والتشخيصات والزخارف، مع اختصارات محررات الشيفرة. النص للتطبيق (value وonChange)، وكذلك شريط البحث الذي يتحكم في search الخاص بالمحرر. ويأتي بمظهر مبني من رموز السمة يعيد التطبيق تنسيقه جزءًا جزءًا. راجع Editor.

#DiffView

يعرض DiffView التغييرات بين نصين، أو في ملفات تصحيح (patch)، كما تفعل أدوات مراجعة الشيفرة: جنبًا إلى جنب أو موحّدًا، مع إبراز الكلمات المتغيرة داخل الأسطر، وطي الأسطر غير المتغيرة في فواصل قابلة للتوسيع، بألوان صياغة Editor. وتحتفظ إجراءات التطبيق بكل تغيير أو تتراجع عنه. راجع DiffView.

#Table

يرتّب Table وأجزاؤه بضعة صفوف يكتبها التطبيق على أنها عناصر فرعية، ويمنح قارئات الشاشة جدولًا: مجموعات من الصفوف، وصفوفًا، ورؤوس أعمدة، وخلايا. يقبل كل جزء مظهر التطبيق. راجع Table.

#DataTable

يعرض DataTable صفوفًا وأعمدة ويتمرّر في الاتجاهين فوق أي عدد منها، ولا يرسم إلا الخلايا الظاهرة. يمكن تحديد الصفوف أو الأعمدة أو الخلايا؛ وتتغير أحجام الأعمدة وتنتقل وتثبت وتُرتَّب (يتولى التطبيق الترتيب)؛ ويقدّم التطبيق الصفوف صفحة صفحة ويمكنه رسم الخلايا والعناوين. راجع DataTable.

#التنقل

NavStack من NavPage هو UINavigationController على iOS، ومكدّس بشريط أدوات ورجوع تنبؤي على Android؛ وعلى أنظمة سطح المكتب والويب تعرض كل صفحة header الخاص بالتطبيق. راجع NavStack، الذي يغطي أيضًا createNavStack ومغادرة الصفحة.

#Dialog

يعرض Dialog المحتوى فوق كل شيء آخر، بما في ذلك ترويسة المكدّس، في طبقة نافذة أصلية خاصة به. ينسّق التطبيق نافذته المنبثقة وخلفيته. راجع Dialog.

#مربعات حوار التنبيه

#AlertDialog

يعرض AlertDialog.show(options) تنبيه المنصة الأصلي أو ورقة الإجراءات، ويُحسم بالقيمة { action }، وهي id الإجراء الذي اختاره المستخدم. راجع AlertDialog.

#الإدخال

Input هو حقل إدخال النص الأصلي للمنصة: حقل بسطر واحد أو متعدد الأسطر تتولى المنصة الكتابة فيه ومؤشر الإدراج والتحديد والتصحيح التلقائي والملء التلقائي. ويملك التطبيق قيمته ومظهره. خصائصه هي النوع InputProps (مع IOSInputProps لـ ios={{…}})، ويُصدَّر بجانبه. راجع Input.

#شريط الحالة

ينتمي شريط الحالة إلى ما هو معروض على الشاشة، كما في UIKit، حيث يعلن كل view controller عن preferredStatusBarStyle الخاص به ويقرر الأعلى منها. في NSH تقوم الصفحات ومربعات الحوار مقام وحدات التحكم هذه: تعلن NavPage أو Dialog عن شريط الحالة الذي تريده عبر statusBar، ويعلن التطبيق إعداده الافتراضي في nsh.json.

use nsh_base::nav_page;
use nsh_core::prelude::*;

fn photo_viewer() -> Screen {
    nav_page().header_visible(false).status_bar(
        StatusBarSetting::default()
            .foreground(StatusBarStyle::Light)
            .hidden(true)
            .animated(true),
    )
}

import { NavPage } from "nsh/base";

function PhotoViewer() {
  return (
    <NavPage headerVisible={false} statusBar={{ foreground: "light", hidden: true, animated: true }}>
      …
    </NavPage>
  );
}

يقبل statusBar هذه الحقول، وكلها اختيارية (في Rust، StatusBarStyle وحده، أو دوال البناء الخاصة بـ StatusBarSetting بالأسماء نفسها):

القيمة تفاعلية: يتبع statusBar={{ foreground: dark() ? "light" : "dark" }} الإشارة، وكذلك يفعل إغلاق Rust الذي يقرأ إشارة.

#أيّها يُطبَّق

تقرر الصفحة أو مربع الحوار المعروض الأحدث، حقلًا بحقل: الصفحة المدفوعة إلى مكدّس تعلو الصفحات التي تحتها، ومربع الحوار المفتوح يعلو الصفحات. وأي حقل تُغفله يأتي من الذي تحتها، وفي النهاية من الإعداد الافتراضي للتطبيق. وعندما تُسحب الصفحة أو يُغلق مربع الحوار، يعود الذي تحتهما إلى التطبيق.

nav_page()
    .title("Inbox")
    .status_bar(StatusBarStyle::Dark);

// Pushed over it: hidden, with the inbox's dark content when it shows again.
nav_page()
    .title("Photo")
    .status_bar(StatusBarSetting::default().hidden(true));

<NavPage title="Inbox" statusBar={{ foreground: "dark" }}>…</NavPage>

// Pushed over it: hidden, with the inbox's dark content when it shows again.
<NavPage title="Photo" statusBar={{ hidden: true }}>…</NavPage>

#الإعداد الافتراضي للتطبيق

"statusBar" في nsh.json هو الإعداد الذي يقع تحت كل صفحة ومربع حوار، كما أن UIStatusBarStyle و UIStatusBarHidden في Info.plist كذلك في تطبيق UIKit:

{
  "statusBar": { "foreground": "light", "hidden": false }
}

كلا الحقلين اختياري. وبدونه يكون المحتوى "auto" ويظهر الشريط. وتعرضه تطبيقات iOS المعبأة أيضًا على شاشة الإطلاق.

#شريط الحالة على كل منصة

• iOS: يتحرك الإخفاء والإظهار بتلاشٍ. وفي تطبيق مضمَّن في تطبيق أصلي، يقرر view controller الخاص بالتطبيق المضيف شكل شريط الحالة. ويطبّق المضيف إعداد NSH بإرجاع NshAppView.preferredStatusBarStyle وNshAppView.prefersStatusBarHidden و NshAppView.preferredStatusBarUpdateAnimation من view controller الخاص به.
• Android: ترسم التطبيقات من حافة إلى حافة، خلف شريط الحالة (Android 15، API 35): خلفية التطبيق نفسها هي خلفية الشريط، ويُبقي foreground محتواه مقروءًا عليها.
• أنظمة سطح المكتب والويب: شريط عنوان النافذة وأشرطة المتصفح تابعة للنظام والمتصفح؛ وstatusBar و"statusBar" الخاص بـ nsh.json مخصصة للهواتف.

{
  "capabilities": {
    "statusBar": true
  }
}

#ذات صلة

• Navigation guide.
• Forms and keyboard.
• Avatar، Button، Carousel، Link، Checkbox، Radio، Switch، Tabs، Toggle، Toolbar، Select، Combobox، Command، Calendar، TimeField، DatePicker، Collapsible، HoverCard، Accordion، Progress، Slider، ColorPicker، Scrollbar، NumberInput، OtpInput، Pagination، Tree، Plot، NavStack، Dialog، AlertDialog، TextView، Editor، DiffView، Table، DataTable، Text وInput. AlertDialog، TextView، Editor، DiffView، Table، DataTable، Text و Input.
• Device and environment.
• BackHandler: BackHandler وواجهات برمجة التطبيقات الأخرى الخاصة بـ Android فقط.