@apliteni/apliteni-ui 0.76.1 → 0.78.0

package/guidelines/file-drop.md

@@ -0,0 +1,87 @@
+# File drop
+
+## Spend one row at rest
+
+<!-- rule: one-row -->
+
+**Rule:** At rest, a file drop is one row: the button that opens the picker and the accepted types beside it.
+
+**Why:** A tall box holds the page's best space open for a file that arrives once a month.
+
+**Do:** Put an Upload button and “PDF or CSV, up to 10 MB” on one line above the list they feed.
+
+**Don't:** Draw a tall dashed box with a glyph, an invitation and a button stacked inside it.
+
+**Except:** A page whose whole purpose is receiving one file may use the field-sized picker, which carries a label of its own.
+
+## Paint the target only while a file is over it
+
+<!-- rule: on-drag -->
+
+**Rule:** Show the drop target while a file is over the region that accepts it, and nowhere else.
+
+**Why:** A target drawn before there is a file to catch covers content the reader still needs.
+
+**Do:** Cover the panel that accepts the file the moment the file crosses it.
+
+**Don't:** Cover the whole window when one panel accepts the file.
+
+## Keep the file in the row it arrived in
+
+<!-- rule: in-the-row -->
+
+**Rule:** After the drop, the file's name, size and progress take the place the button was in, with remove on the name's line.
+
+**Why:** A row that changes in place keeps the page still while the file uploads.
+
+**Do:** Give the name a line with remove at its end, put the size under it, and run the progress track the full width below both.
+
+**Don't:** Push the list down with a progress card, or open a dialog over the page.
+
+## Fail in place
+
+<!-- rule: failure -->
+
+**Rule:** A refused file keeps its place, says what it did wrong under its name, and offers Retry beside Remove.
+
+**Why:** A row that drops the file sends the reader back to choosing one. The reason is the one string here that has to be read in full, so it gets a line rather than a share of one.
+
+**Do:** Keep the name on its line and say “Larger than 10 MB” under it, with Retry.
+
+**Don't:** Replace the row with “Upload failed”, losing both the file and the retry.
+
+## Offer a button, not only a drag
+
+<!-- rule: button-path -->
+
+**Rule:** Give the reader a button that opens the picker, and let dragging be the shortcut.
+
+**Why:** A keyboard cannot drag a file.
+
+**Do:** Make the Upload button the control, reachable by keyboard and showing the focus ring.
+
+**Don't:** Write “Drag a file here” with nothing to press.
+
+## State the limits once
+
+<!-- rule: limits-once -->
+
+**Rule:** Name the accepted types and the size limit once, beside the button, in the product's own words.
+
+**Why:** Repeated limits teach the reader to skip them.
+
+**Do:** Write “PDF or CSV, up to 10 MB” beside the button, and let a failure say what this file did wrong.
+
+**Don't:** Repeat the limits under the button, in a tooltip and again in the error.
+
+## Choose the row, the region or the dialog
+
+<!-- rule: which-shape -->
+
+**Rule:** Use a row where the file joins a list on the page, a region when one panel owns the file, and a dialog only when the upload needs answers of its own.
+
+**Why:** A dialog that asks nothing is one more thing to dismiss. The rule picks between three containers, so a drawing would show one of them and not the choice.
+
+**Do:** Take a statement into the row under the statements it joins, and a replacement logo into the panel that shows it.
+
+**Don't:** Open a dialog for one file that the row behind it could have taken.

package/guidelines/state-set.md

@@ -12,7 +12,7 @@
 
 **Don't:** Give the input a separate muted outline while the button uses `--ring`.
 
-**Except:** Text-entry controls may match `:focus-visible` on mouse focus. Surface backgrounds set the gap colour and recompose `--ring`; adjust width and colour at the root.
+**Except:** A scroll region inside a surface takes `--ring-scroll`: the same 1px gap and 2px band, drawn inward, without the halo. `--ring` is drawn for a 32px control, where the halo is a glint; around a 400px region it spreads 14px past the band and lights the surface instead of the box that scrolls. A box that is itself the outermost surface — a panel, a card — keeps `--ring`. Text-entry controls may match `:focus-visible` on mouse focus. Surface backgrounds set the gap colour and recompose `--ring`; adjust width and colour at the root.
 
 ## Busy controls
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.76.1",
+  "version": "0.78.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -493,6 +493,34 @@ places a decorative kit glyph with `icon` — the same glyph names `Button` and
 `onFileChange`. Use `accept` and `hint` to describe allowed file types and size.
 Your application must validate files before upload.
 
+## File drop
+
+`FileDrop` is the compact drop: one row with the button that opens the picker and
+the accepted types beside it, and a drop target painted only while a file is over
+the region. Use it where a file joins a list on the page; use `FileField` where a
+labelled, field-sized picker belongs. The guideline page states when to use a row,
+a region or a dialog.
+
+```tsx
+<FileDrop note="PDF or CSV, up to 10 MB" accept=".pdf,.csv"
+  file={upload} onFile={send} onRemove={clear} onRetry={send} />
+```
+
+Your application owns the upload and supplies the `file` it is holding: the
+name, the `size` already written for a reader, `progress` while it uploads, and
+the `error` when it failed. A file with no `status` is uploading, so a file
+handed over before the request starts never reads as uploaded. A status the row
+draws shows a mark and a word; where you give `progress` the track says it
+instead, and the word goes to the track's accessible name. The file reads as a
+stack: the name on top with the actions at its end, the size — or the failure
+message — under it, and the track the full width below. No tier takes a second
+line. The name truncates its stem and keeps its extension, with the whole name in
+a `title`, and nothing is hidden or moved at any width. `Remove` is the icon-only
+`x`, named by `removeLabel`; `Retry` keeps its word. Both appear only when you
+handle them. Children render above the row, inside the region the target covers;
+pass `dragging` to drive that target from a parent. `accept` filters the system
+picker only — validate type and size yourself.
+
 Use `Field` when an existing labelled control needs the kit frame. Spread its
 render-prop attributes onto one labelable control, and apply the existing control
 class and invalid styling as appropriate:

package/react/dist/index.css

@@ -82,6 +82,14 @@
   .ui-table__act .ui-btn + .ui-btn {
     margin-inline-start: var(--tap-gap) !important;
   }
+  .ui-drop__row {
+    --tap-clear-y: var(--tap-gap);
+  }
+  .ui-drop__actions {
+    gap: var(--tap-gap) !important;
+    --tap-clear-x: var(--tap-gap);
+    --tap-clear-y: var(--tap-gap);
+  }
   .ui-table__act {
     --tap-clear-x: var(--tap-gap);
     --tap-clear-y: 0px;
@@ -216,6 +224,10 @@
   min-height: 0;
   overflow: auto;
 }
+.rx-modal__body:focus-visible {
+  outline: var(--ring-scroll);
+  outline-offset: var(--ring-scroll-offset);
+}
 .rx-modal__body > * {
   flex-shrink: 0;
 }
@@ -494,6 +506,129 @@
   cursor: not-allowed;
 }
 
+/* ../src/styles/file-drop.css */
+.ui-drop {
+  position: relative;
+}
+.ui-drop > * + .ui-drop__row {
+  margin-top: var(--space-3);
+}
+.ui-drop__row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  min-height: var(--space-8);
+  gap: var(--space-2) var(--space-3);
+  font-size: var(--text-sm);
+  color: var(--text);
+  overflow-wrap: anywhere;
+}
+.ui-drop__note {
+  margin: 0;
+}
+.ui-drop__file {
+  display: grid;
+  flex: 1 1 auto;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.ui-drop__line {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+.ui-drop__name {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: var(--space-10);
+  color: var(--strong);
+  font-weight: var(--weight-medium);
+}
+.ui-drop__stem {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.ui-drop__ext {
+  flex: none;
+}
+.ui-drop__facts {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+.ui-drop__size {
+  flex: none;
+  white-space: nowrap;
+}
+.ui-drop__word {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 0 1 auto;
+  min-width: 0;
+}
+.ui-drop__state {
+  display: inline-flex;
+  flex: 0 1 auto;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.ui-drop__state svg {
+  width: 16px;
+  height: 16px;
+  flex: none;
+  stroke-width: 2.4;
+}
+.ui-drop__error {
+  color: var(--pink);
+}
+.ui-drop__actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--space-2);
+  margin-left: auto;
+}
+.ui-drop__bar {
+  display: block;
+  width: 100%;
+  height: 6px;
+  border-radius: var(--radius-pill);
+  background: var(--surface-2);
+  overflow: hidden;
+}
+.ui-drop__bar span {
+  display: block;
+  height: 100%;
+  background: var(--accent);
+}
+.ui-drop__target {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--space-3);
+  border: 1px dashed var(--accent);
+  border-radius: var(--radius-md);
+  background: var(--surface);
+  color: var(--strong);
+  font-size: var(--text-sm);
+  text-align: center;
+}
+.ui-drop.is-disabled .ui-drop__row {
+  color: var(--disabled-ink);
+}
+.ui-drop.is-disabled .ui-drop__name {
+  color: var(--disabled-ink);
+}
+
 /* src/Toast.css */
 .rx-toast-stack {
   position: fixed;

package/react/dist/index.d.ts

@@ -607,6 +607,47 @@ type FileFieldProps = FieldMessage & Omit<InputHTMLAttributes<HTMLInputElement>,
 };
 declare function FileField({ label, hint, error, required, disabled, onFileChange, className, ...props }: FileFieldProps): react.JSX.Element;
 
+type FileDropStatus = 'uploading' | 'done' | 'error';
+/** The file the consumer is uploading. */
+type FileDropFile = {
+    name: string;
+    /** Already written for a reader; the kit picks no unit. */
+    size?: string;
+    /** Left out, the file is uploading: the kit never reports a success nobody claimed. */
+    status?: FileDropStatus;
+    /** 0 to 100. Left out, the word stands without a bar. */
+    progress?: number;
+    /** What this file did wrong, when the status is an error. */
+    error?: string;
+    /** Replaces the word the status carries. */
+    state?: string;
+};
+type FileDropProps = {
+    /** The button that opens the picker. */
+    label?: string;
+    /** The accepted types and the size limit, stated once beside the button. */
+    note?: string;
+    /** Filters the system picker only; the consumer still validates the file. */
+    accept?: string;
+    /** The words on the drop target. */
+    dropLabel?: string;
+    /** Names the icon-only remove button; it carries no visible word. */
+    removeLabel?: string;
+    retryLabel?: string;
+    /** The file the consumer is holding. Left out, the row is at rest. */
+    file?: FileDropFile | null;
+    /** Drives the target from a parent that owns the drag region. */
+    dragging?: boolean;
+    disabled?: boolean;
+    onFile?: (file: File) => void;
+    onRemove?: () => void;
+    onRetry?: () => void;
+    /** What the region accepts the file for; the target covers it while dragging. */
+    children?: ReactNode;
+    className?: string;
+};
+declare function FileDrop({ label, note, accept, dropLabel, removeLabel, retryLabel, file, dragging, disabled, onFile, onRemove, onRetry, children, className, }: FileDropProps): react.JSX.Element;
+
 type SearchFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'aria-label'> & {
     /** The control's name. A toolbar search box shows no label, so this is the
         only name it has. */
@@ -827,4 +868,4 @@ declare const SidebarNav: react.ForwardRefExoticComponent<Omit<Omit<react.Detail
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };