react-native-layout-dnd 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 baesumin
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+# React Native Layout DnD
+
+Drag and drop for React Native grids and lists, built on Reanimated worklets and
+Gesture Handler.
+
+One provider owns a normalized layout state. An item can be reordered inside a
+list, placed by coordinates in a grid, or moved between the two, and every move
+arrives at your state layer as one complete candidate that you can accept or
+reject.
+
+> **Pre-release.** This package is not on npm yet, and its peer versions are
+> pinned to the exact combination it has been verified against. Read
+> [Status and limitations](#status-and-limitations) before adopting it.
+
+## Why this library
+
+- **Grids and lists in one drag session.** A single `DndProvider` hosts any
+  number of list and grid zones. List-to-list, grid-to-grid and list-to-grid
+  moves all produce one candidate and one approval.
+- **Grids with mixed spans.** Items occupy `rows x cols` cells at explicit
+  coordinates. Insertion and exchange are separate placement policies, and
+  rules such as full-width row rotation are configurable per provider.
+- **Ordered grid zones.** Give a grid zone an `itemSpan` and it behaves like a
+  dock: array order is item order, a move inserts at the addressed slot,
+  removal closes the gap, and capacity is the slot count.
+- **Lists that scroll.** Vertical and horizontal, fixed or measured variable
+  sizes, edge auto-scroll during a drag, and optional `FlatList` windowing for
+  long lists.
+- **Your state stays in control.** Every move is a revisioned proposal. Reject
+  it synchronously with `canDrop`, or answer asynchronously within a timeout.
+  Rejection, cancellation and expiry restore the current layout without
+  overwriting a later external edit.
+- **A pure engine you can call directly.** `react-native-layout-dnd/engine`
+  computes moves, packing and layout without loading React Native components,
+  so input that is not a gesture, such as a screen-reader action or an undo,
+  uses exactly the same rules as dragging.
+
+## Requirements
+
+| Peer dependency              | Accepted range   | Verified |
+| ---------------------------- | ---------------- | -------- |
+| React Native                 | `>=0.78.0`       | 0.87.1   |
+| React Native Gesture Handler | `>=3.0.0 <4.0.0` | 3.3.0    |
+| React Native Reanimated      | `>=4.0.0 <5.0.0` | 4.6.0    |
+| React Native Worklets        | `>=0.5.0 <1.0.0` | 0.12.2   |
+
+React is a peer too, at 19 or newer, but your React Native version already
+decides it. The New Architecture is required, because Reanimated 4 supports
+nothing else.
+
+Each lower bound is the release that introduced an API this package calls: the
+v3 gesture hooks in Gesture Handler 3.0.0, the worklets package split in
+Reanimated 4.0.0, and `scheduleOnUI`, `scheduleOnRN` and `runOnUISync` in
+Worklets 0.5.0. Only the **Verified** column has actually been built and run
+end to end, so treat the rest of the range as accepted rather than tested, and
+pin what works for you. Reanimated and Worklets constrain your React Native
+version further through their own peer ranges.
+
+Your app must also render the provider under `GestureHandlerRootView` and enable
+the Worklets Babel plugin. This package ships worklet directives uncompiled so
+that your plugin version transforms them:
+
+```js
+// babel.config.js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: ['react-native-worklets/plugin'],
+};
+```
+
+## Installation
+
+Not published yet. Build a tarball from a clone and install it by path:
+
+```sh
+git clone https://github.com/baesumin/react-native-layout-dnd.git
+cd react-native-layout-dnd
+yarn install
+npm pack
+```
+
+```sh
+# in your app
+yarn add /absolute/path/to/react-native-layout-dnd-0.1.0-alpha.0.tgz
+```
+
+Installing straight from the Git URL does not work, because the entry points
+come from a build that only runs while packing.
+
+## Quick start
+
+A sortable vertical list. `useDndState` holds the layout and acknowledges each
+proposal for you, and `DragHandle` marks the part of an item that starts a drag.
+
+```tsx
+import { Text, View } from 'react-native';
+import {
+  DndProvider,
+  DragHandle,
+  SortableList,
+  useDndState,
+  type LayoutState,
+} from 'react-native-layout-dnd';
+
+type Task = { title: string };
+
+const initial: LayoutState<Task> = {
+  revision: 0,
+  items: [
+    { id: 'a', data: { title: 'Notes' } },
+    { id: 'b', data: { title: 'Plan' } },
+  ],
+  zones: [
+    { id: 'tasks', kind: 'list', orientation: 'vertical', itemIds: ['a', 'b'] },
+  ],
+};
+
+export function Tasks() {
+  const { value, onChange } = useDndState(initial);
+  return (
+    <DndProvider value={value} onChange={onChange} style={{ flex: 1 }}>
+      <SortableList<Task>
+        zoneId="tasks"
+        style={{ flex: 1 }}
+        estimatedItemSize={72}
+        gap={8}
+        renderItem={({ item }) => (
+          <View style={{ padding: 12 }}>
+            <DragHandle>
+              <Text>{item.data.title}</Text>
+            </DragHandle>
+          </View>
+        )}
+      />
+    </DndProvider>
+  );
+}
+```
+
+The provider and every zone need a bounded viewport, for example `flex: 1`
+inside a bounded parent. A drag starts after a 250 ms long press by default.
+
+### Moving between a list and a grid
+
+Add a `SortableGrid` to the same provider. A list item carries no grid
+footprint, so `getGridItemLayout` decides the span an incoming item takes. Keep
+that function stable, because it is captured once per drag.
+
+```tsx
+<DndProvider
+  value={value}
+  onChange={onChange}
+  getGridItemLayout={({ item }) => ({
+    span: item.data.span,
+    placement: 'insert',
+  })}
+  style={{ flex: 1 }}
+>
+  <SortableList<Card> zoneId="library" virtualization ... />
+  <SortableGrid<Card>
+    zoneId="board"
+    style={{ height: 240 }}
+    geometry={{
+      mode: 'fit',
+      rowGap: 8,
+      columnGap: 8,
+      padding: { top: 8, right: 8, bottom: 8, left: 8 },
+    }}
+    renderItem={({ item, width, height }) => (
+      <View style={{ width, height }}>
+        <DragHandle>
+          <Text>{item.data.title}</Text>
+        </DragHandle>
+      </View>
+    )}
+  />
+</DndProvider>
+```
+
+A grid zone with `rows`, `columns` and `placements` is spatial. Add `itemSpan`
+and it becomes an ordered zone instead, which is how a dock behaves.
+
+## How a move reaches your state
+
+1. The gesture resolves a target cell or index.
+2. The engine computes the **whole next layout**, including every item the move
+   displaces. It never commits partial work, so a move that cannot be placed
+   fails as a whole.
+3. `canDrop(proposal)` may reject the candidate synchronously, during the
+   preview and again at release.
+4. `onChange(next, proposal)` publishes the candidate together with
+   `proposal.baseRevision`. Answer it by committing a value whose revision is
+   that base plus one, or by rejecting it. `useDndState` and
+   `createDndStateStore` do this for you.
+5. `onDragEnd` reports the outcome: `accepted`, `rejected`, `expired`,
+   `mismatch`, `interrupted`, or a cancellation with its reason.
+
+An unanswered proposal expires after `responseTimeoutMs`, 2000 ms by default,
+and an external edit during a drag interrupts the session instead of being
+overwritten.
+
+For input that is not a gesture, compute the same move and commit it yourself:
+
+```ts
+import { computeLayoutMove } from 'react-native-layout-dnd/engine';
+
+const result = computeLayoutMove({
+  value,
+  itemId,
+  to: { kind: 'list', zoneId: 'tasks', index: targetIndex },
+});
+if (result.status === 'ok' && result.changed) setValue(result.value);
+```
+
+## Documentation
+
+- [Lists and scrolling](docs/list-scroll-api.md) covers `DndProvider`,
+  `SortableList`, `DragHandle`, `useDndState`, virtualization, auto-scroll and
+  accessibility.
+- [Grids and mixed layouts](docs/mixed-layout-api.md) covers `SortableGrid`,
+  spans, transfers between zones, approval and failure reasons.
+- [Grid contracts and the `GridController` API](docs/api.md) covers the shared
+  layout contract, movement policies and preview rules, plus the grid-only API
+  kept for existing consumers, which is now an adapter over the same provider.
+- [Contributing](CONTRIBUTING.md) lists the checks and the native test
+  checklist.
+
+Runnable examples live in [`example/`](example/), including a 580-item
+`FlatList` tab and a mixed grid and list screen:
+
+```sh
+yarn install
+yarn example start
+yarn example ios     # or: yarn example android
+```
+
+## Status and limitations
+
+Automated verification passes 51 suites and 1,215 tests, seven
+performance-tooling tests, TypeScript, ESLint, the build, and an isolated check
+of the packed API and its types.
+
+Known gaps, stated so you can judge the risk:
+
+- **Not published.** The package stays `private` until the release criteria are
+  met, and the public API may still change.
+- **One verified combination.** The peer ranges above come from the APIs this
+  package calls, not from a test matrix. Only the versions in the Verified
+  column have been built and run, and Expo has not been tried.
+- **Device verification is incomplete.** iOS simulator measurement and an
+  Android emulator driver pass. Dragging across rotation and app backgrounding,
+  Android release-build touch input, and a physical-device run are still open.
+- **Screen readers.** Handles forward accessibility view props and reduced
+  motion follows the system setting, but the drag state itself is not announced
+  and no move actions are wired up for you. See the
+  [accessibility support level](docs/list-scroll-api.md#accessibility-reduced-motion-and-alternative-movement).
+- **Virtualization is list-only.** Grid zones render every placement, and there
+  are no FlashList or LegendList adapters.
+
+## License
+
+[MIT](LICENSE) — baesumin.

package/lib/module/adapters/coordinates.js

@@ -0,0 +1,135 @@
+"use strict";
+
+import { isRecord } from "../engine/validation.js";
+function isPoint(value) {
+  return isRecord(value) && typeof value.x === 'number' && Number.isFinite(value.x) && typeof value.y === 'number' && Number.isFinite(value.y);
+}
+function isRect(value) {
+  return isPoint(value) && 'width' in value && typeof value.width === 'number' && Number.isFinite(value.width) && value.width > 0 && 'height' in value && typeof value.height === 'number' && Number.isFinite(value.height) && value.height > 0;
+}
+function isNonnegativeFinite(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/** Estimates remain estimates after validation; callers must inspect source. */
+export function validateRectMeasurement(measurement, freshness) {
+  if (!isRecord(freshness) || !Number.isSafeInteger(freshness.revision) || freshness.revision < 0 || freshness.nowMs === undefined !== (freshness.maxAgeMs === undefined) || freshness.nowMs !== undefined && (!isNonnegativeFinite(freshness.nowMs) || !isNonnegativeFinite(freshness.maxAgeMs))) {
+    return {
+      valid: false,
+      reason: 'invalid-freshness'
+    };
+  }
+  if (!isRecord(measurement) || measurement.source !== 'measured' && measurement.source !== 'estimated' || measurement.space !== 'screen' && measurement.space !== 'content' || !isRect(measurement.rect) || !Number.isSafeInteger(measurement.revision) || measurement.revision < 0 || !isNonnegativeFinite(measurement.timestampMs)) {
+    return {
+      valid: false,
+      reason: 'invalid-measurement'
+    };
+  }
+  if (measurement.revision !== freshness.revision || freshness.nowMs !== undefined && (measurement.timestampMs > freshness.nowMs || freshness.nowMs - measurement.timestampMs > freshness.maxAgeMs)) {
+    return {
+      valid: false,
+      reason: 'stale-measurement'
+    };
+  }
+  return {
+    valid: true,
+    value: measurement
+  };
+}
+function validateContext(context, freshness) {
+  if (!isRecord(context) || !isPoint(context.scrollOffset)) {
+    return {
+      valid: false,
+      reason: 'invalid-context'
+    };
+  }
+  const measurement = validateRectMeasurement(context.viewport, freshness);
+  if (!measurement.valid) return measurement;
+  if (measurement.value.source !== 'measured' || measurement.value.space !== 'screen') {
+    return {
+      valid: false,
+      reason: 'invalid-context'
+    };
+  }
+  return {
+    valid: true,
+    value: context
+  };
+}
+function convertPoint(point, context, freshness, direction) {
+  if (!isPoint(point)) return {
+    valid: false,
+    reason: 'invalid-coordinate'
+  };
+  const validation = validateContext(context, freshness);
+  if (!validation.valid) return validation;
+  const {
+    rect
+  } = context.viewport;
+  const {
+    scrollOffset
+  } = context;
+  const value = direction === 'to-content' ? {
+    x: point.x - rect.x + scrollOffset.x,
+    y: point.y - rect.y + scrollOffset.y
+  } : {
+    x: point.x - scrollOffset.x + rect.x,
+    y: point.y - scrollOffset.y + rect.y
+  };
+  return isPoint(value) ? {
+    valid: true,
+    value
+  } : {
+    valid: false,
+    reason: 'invalid-coordinate'
+  };
+}
+
+/** Convert absolute screen pixels to zone content pixels using the current offset. */
+export function screenToContent(point, context, freshness) {
+  return convertPoint(point, context, freshness, 'to-content');
+}
+export function contentToScreen(point, context, freshness) {
+  return convertPoint(point, context, freshness, 'to-screen');
+}
+export function screenRectToContent(measurement, context, freshness) {
+  const validation = validateRectMeasurement(measurement, freshness);
+  if (!validation.valid) return validation;
+  if (measurement.space !== 'screen') return {
+    valid: false,
+    reason: 'invalid-measurement'
+  };
+  const converted = screenToContent(measurement.rect, context, freshness);
+  return converted.valid ? {
+    valid: true,
+    value: {
+      ...measurement,
+      space: 'content',
+      rect: {
+        ...measurement.rect,
+        ...converted.value
+      }
+    }
+  } : converted;
+}
+export function contentRectToScreen(measurement, context, freshness) {
+  const validation = validateRectMeasurement(measurement, freshness);
+  if (!validation.valid) return validation;
+  if (measurement.space !== 'content') return {
+    valid: false,
+    reason: 'invalid-measurement'
+  };
+  const converted = contentToScreen(measurement.rect, context, freshness);
+  return converted.valid ? {
+    valid: true,
+    value: {
+      ...measurement,
+      space: 'screen',
+      rect: {
+        ...measurement.rect,
+        ...converted.value
+      }
+    }
+  } : converted;
+}
+//# sourceMappingURL=coordinates.js.map

package/lib/module/adapters/coordinates.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isRecord","isPoint","value","x","Number","isFinite","y","isRect","width","height","isNonnegativeFinite","validateRectMeasurement","measurement","freshness","isSafeInteger","revision","nowMs","undefined","maxAgeMs","valid","reason","source","space","rect","timestampMs","validateContext","context","scrollOffset","viewport","convertPoint","point","direction","validation","screenToContent","contentToScreen","screenRectToContent","converted","contentRectToScreen"],"sourceRoot":"../../../src","sources":["adapters/coordinates.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/adapters/scroll.js

@@ -0,0 +1,81 @@
+"use strict";
+
+/** The permitted drag direction is independent of a list's orientation. */
+
+/** One axis of a measured scroll viewport, using logical pixels throughout. */
+
+/** Validate public options before activating a gesture or executing a frame. */
+export function validateAutoScrollOptions(options) {
+  'worklet';
+
+  if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options) || options.enabled !== undefined && typeof options.enabled !== 'boolean' || options.edgeThreshold !== undefined && (!Number.isFinite(options.edgeThreshold) || options.edgeThreshold <= 0) || options.maxSpeed !== undefined && (!Number.isFinite(options.maxSpeed) || options.maxSpeed < 0))) return {
+    valid: false,
+    reason: 'invalid-options'
+  };
+  return {
+    valid: true
+  };
+}
+
+/**
+ * Compute one frame of edge scrolling for either orientation. Adapters should
+ * call scrollTo only for nonzero velocity, preserving native bounce while idle.
+ * Call only during an active drag, and re-read its candidate after scrolling.
+ */
+export function computeAutoScroll(input) {
+  'worklet';
+
+  if (!input || typeof input !== 'object' || Array.isArray(input) || !Number.isFinite(input.pointer) || !Number.isFinite(input.viewportStart) || !Number.isFinite(input.viewportSize) || input.viewportSize <= 0 || !Number.isFinite(input.offset) || !Number.isFinite(input.contentSize) || input.contentSize < 0 || !Number.isFinite(input.deltaTimeMs) || input.deltaTimeMs < 0) return {
+    valid: false,
+    reason: 'invalid-input'
+  };
+  const {
+    options
+  } = input;
+  const validation = validateAutoScrollOptions(options);
+  if (!validation.valid) return validation;
+  const maximum = Math.max(0, input.contentSize - input.viewportSize);
+  const offset = Math.max(0, Math.min(maximum, input.offset));
+  const idle = {
+    valid: true,
+    offset,
+    velocity: 0
+  };
+  const pointer = input.pointer - input.viewportStart;
+  if (!Number.isFinite(pointer)) return {
+    valid: false,
+    reason: 'invalid-input'
+  };
+  if (options?.enabled === false || pointer < 0 || pointer > input.viewportSize || maximum === 0 || input.deltaTimeMs === 0) return idle;
+
+  // Cap overlapping edge bands at the midpoint so tiny viewports do not bias
+  // toward the first edge. The exact midpoint has no preferred direction.
+  const threshold = Math.min(options?.edgeThreshold ?? 48, input.viewportSize / 2);
+  if (threshold === 0) return idle;
+  const trailingDistance = input.viewportSize - pointer;
+  const direction = pointer < threshold ? -1 : trailingDistance < threshold ? 1 : 0;
+  if (direction === 0) return idle;
+  const distance = direction < 0 ? pointer : trailingDistance;
+  const speed = (options?.maxSpeed ?? 600) * (1 - distance / threshold);
+  // A paused/resumed frame must not skip a large portion of the list.
+  const seconds = Math.min(input.deltaTimeMs, 64) / 1000;
+  if (seconds === 0 || speed === 0) return idle;
+  const nextOffset = Math.max(0, Math.min(maximum, offset + direction * speed * seconds));
+  const movement = nextOffset - offset;
+  return {
+    valid: true,
+    offset: nextOffset,
+    velocity: movement === 0 ? 0 : direction * Math.min(speed, Math.abs(movement / seconds))
+  };
+}
+
+/** Project a validated screen point onto the configured axis through origin. */
+export function constrainDragPoint(point, origin, axis) {
+  'worklet';
+
+  return {
+    x: axis === 'y' ? origin.x : point.x,
+    y: axis === 'x' ? origin.y : point.y
+  };
+}
+//# sourceMappingURL=scroll.js.map

package/lib/module/adapters/scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["validateAutoScrollOptions","options","undefined","Array","isArray","enabled","edgeThreshold","Number","isFinite","maxSpeed","valid","reason","computeAutoScroll","input","pointer","viewportStart","viewportSize","offset","contentSize","deltaTimeMs","validation","maximum","Math","max","min","idle","velocity","threshold","trailingDistance","direction","distance","speed","seconds","nextOffset","movement","abs","constrainDragPoint","point","origin","axis","x","y"],"sourceRoot":"../../../src","sources":["adapters/scroll.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/adapters/virtualizedList.js

@@ -0,0 +1,69 @@
+"use strict";
+
+import { isPositiveInteger, isRecord } from "../engine/validation.js";
+
+/** FlatList rendering limits; enabling virtualization preserves the layout API. */
+
+const DEFAULT_OPTIONS = Object.freeze({
+  initialNumToRender: 12,
+  maxToRenderPerBatch: 12,
+  windowSize: 7,
+  updateCellsBatchingPeriod: 50
+});
+function invalid(message) {
+  return {
+    valid: false,
+    issues: [{
+      code: 'invalid-configuration',
+      message
+    }]
+  };
+}
+
+/** Undefined/false selects ScrollView; true or an options object selects FlatList. */
+export function resolveListVirtualization(value) {
+  if (value === undefined || value === false) {
+    return {
+      valid: true,
+      options: null
+    };
+  }
+  if (value === true) return {
+    valid: true,
+    options: {
+      ...DEFAULT_OPTIONS
+    }
+  };
+  if (!isRecord(value)) {
+    return invalid('virtualization must be a boolean or an options object.');
+  }
+  if (Object.keys(value).some(key => key !== 'initialNumToRender' && key !== 'maxToRenderPerBatch' && key !== 'windowSize' && key !== 'updateCellsBatchingPeriod')) {
+    return invalid('virtualization supports only initialNumToRender, maxToRenderPerBatch, windowSize and updateCellsBatchingPeriod.');
+  }
+  const initialNumToRender = value.initialNumToRender === undefined ? DEFAULT_OPTIONS.initialNumToRender : value.initialNumToRender;
+  const maxToRenderPerBatch = value.maxToRenderPerBatch === undefined ? DEFAULT_OPTIONS.maxToRenderPerBatch : value.maxToRenderPerBatch;
+  const windowSize = value.windowSize === undefined ? DEFAULT_OPTIONS.windowSize : value.windowSize;
+  const updateCellsBatchingPeriod = value.updateCellsBatchingPeriod === undefined ? DEFAULT_OPTIONS.updateCellsBatchingPeriod : value.updateCellsBatchingPeriod;
+  if (!isPositiveInteger(initialNumToRender)) {
+    return invalid('virtualization.initialNumToRender must be a positive safe integer.');
+  }
+  if (!isPositiveInteger(maxToRenderPerBatch)) {
+    return invalid('virtualization.maxToRenderPerBatch must be a positive safe integer.');
+  }
+  if (typeof windowSize !== 'number' || !Number.isFinite(windowSize) || windowSize <= 1) {
+    return invalid('virtualization.windowSize must be finite and greater than 1.');
+  }
+  if (typeof updateCellsBatchingPeriod !== 'number' || !Number.isFinite(updateCellsBatchingPeriod) || updateCellsBatchingPeriod < 0) {
+    return invalid('virtualization.updateCellsBatchingPeriod must be finite and nonnegative.');
+  }
+  return {
+    valid: true,
+    options: {
+      initialNumToRender,
+      maxToRenderPerBatch,
+      windowSize,
+      updateCellsBatchingPeriod
+    }
+  };
+}
+//# sourceMappingURL=virtualizedList.js.map

package/lib/module/adapters/virtualizedList.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isPositiveInteger","isRecord","DEFAULT_OPTIONS","Object","freeze","initialNumToRender","maxToRenderPerBatch","windowSize","updateCellsBatchingPeriod","invalid","message","valid","issues","code","resolveListVirtualization","value","undefined","options","keys","some","key","Number","isFinite"],"sourceRoot":"../../../src","sources":["adapters/virtualizedList.ts"],"mappings":";;AACA,SAASA,iBAAiB,EAAEC,QAAQ,QAAQ,yBAAsB;;AAElE;;AAgBA,MAAMC,eAA8D,GAClEC,MAAM,CAACC,MAAM,CAAC;EACZC,kBAAkB,EAAE,EAAE;EACtBC,mBAAmB,EAAE,EAAE;EACvBC,UAAU,EAAE,CAAC;EACbC,yBAAyB,EAAE;AAC7B,CAAC,CAAC;AAEJ,SAASC,OAAOA,CAACC,OAAe,EAA4B;EAC1D,OAAO;IACLC,KAAK,EAAE,KAAK;IACZC,MAAM,EAAE,CAAC;MAAEC,IAAI,EAAE,uBAAuB;MAAEH;IAAQ,CAAC;EACrD,CAAC;AACH;;AAEA;AACA,OAAO,SAASI,yBAAyBA,CACvCC,KAAc,EACY;EAC1B,IAAIA,KAAK,KAAKC,SAAS,IAAID,KAAK,KAAK,KAAK,EAAE;IAC1C,OAAO;MAAEJ,KAAK,EAAE,IAAI;MAAEM,OAAO,EAAE;IAAK,CAAC;EACvC;EACA,IAAIF,KAAK,KAAK,IAAI,EAAE,OAAO;IAAEJ,KAAK,EAAE,IAAI;IAAEM,OAAO,EAAE;MAAE,GAAGf;IAAgB;EAAE,CAAC;EAC3E,IAAI,CAACD,QAAQ,CAACc,KAAK,CAAC,EAAE;IACpB,OAAON,OAAO,CAAC,wDAAwD,CAAC;EAC1E;EACA,IACEN,MAAM,CAACe,IAAI,CAACH,KAAK,CAAC,CAACI,IAAI,CACrBC,GAAG,IACDA,GAAG,KAAK,oBAAoB,IAC5BA,GAAG,KAAK,qBAAqB,IAC7BA,GAAG,KAAK,YAAY,IACpBA,GAAG,KAAK,2BACZ,CAAC,EACD;IACA,OAAOX,OAAO,CACZ,iHACF,CAAC;EACH;EACA,MAAMJ,kBAAkB,GACtBU,KAAK,CAACV,kBAAkB,KAAKW,SAAS,GAClCd,eAAe,CAACG,kBAAkB,GAClCU,KAAK,CAACV,kBAAkB;EAC9B,MAAMC,mBAAmB,GACvBS,KAAK,CAACT,mBAAmB,KAAKU,SAAS,GACnCd,eAAe,CAACI,mBAAmB,GACnCS,KAAK,CAACT,mBAAmB;EAC/B,MAAMC,UAAU,GACdQ,KAAK,CAACR,UAAU,KAAKS,SAAS,GAC1Bd,eAAe,CAACK,UAAU,GAC1BQ,KAAK,CAACR,UAAU;EACtB,MAAMC,yBAAyB,GAC7BO,KAAK,CAACP,yBAAyB,KAAKQ,SAAS,GACzCd,eAAe,CAACM,yBAAyB,GACzCO,KAAK,CAACP,yBAAyB;EACrC,IAAI,CAACR,iBAAiB,CAACK,kBAAkB,CAAC,EAAE;IAC1C,OAAOI,OAAO,CACZ,oEACF,CAAC;EACH;EACA,IAAI,CAACT,iBAAiB,CAACM,mBAAmB,CAAC,EAAE;IAC3C,OAAOG,OAAO,CACZ,qEACF,CAAC;EACH;EACA,IACE,OAAOF,UAAU,KAAK,QAAQ,IAC9B,CAACc,MAAM,CAACC,QAAQ,CAACf,UAAU,CAAC,IAC5BA,UAAU,IAAI,CAAC,EACf;IACA,OAAOE,OAAO,CACZ,8DACF,CAAC;EACH;EACA,IACE,OAAOD,yBAAyB,KAAK,QAAQ,IAC7C,CAACa,MAAM,CAACC,QAAQ,CAACd,yBAAyB,CAAC,IAC3CA,yBAAyB,GAAG,CAAC,EAC7B;IACA,OAAOC,OAAO,CACZ,0EACF,CAAC;EACH;EACA,OAAO;IACLE,KAAK,EAAE,IAAI;IACXM,OAAO,EAAE;MACPZ,kBAAkB;MAClBC,mBAAmB;MACnBC,UAAU;MACVC;IACF;EACF,CAAC;AACH","ignoreList":[]}