@effijs/templates 0.0.0-stage → 1.0.0-alpha.1

package/platforms/react-native/solutions/components/Ruler/files/Value.tsx

@@ -0,0 +1,60 @@
+import { useMemo } from 'react';
+import { StyleSheet, TextInput, type TextInputProps } from 'react-native';
+import Animated, { useAnimatedProps } from 'react-native-reanimated';
+
+import { useRuler } from './Context';
+import type { IRulerValueProps } from './ruler.types';
+import { formatRulerValue } from './ruler.utils';
+
+const VALUE_FONT_SIZE = 32;
+
+const AnimatedTextInput = Animated.createAnimatedComponent(TextInput, {
+  jsProps: ['text', 'defaultValue'],
+});
+
+function estimateValueWidth(charCount: number, fontSize: number): number {
+  return Math.ceil(charCount * fontSize * 0.62) + 4;
+}
+
+export default function RulerValue({ unit, unitStyle, valueStyle, children }: IRulerValueProps) {
+  const context = useRuler();
+
+  const valueWidth = useMemo(() => {
+    const longestValue = formatRulerValue(context.max, context.fractionDigits);
+    const charCount = longestValue.length + (unit ? unit.length + 1 : 0);
+
+    return estimateValueWidth(charCount, VALUE_FONT_SIZE);
+  }, [context.fractionDigits, context.max, unit]);
+
+  const animatedProps = useAnimatedProps(() => {
+    const text = unit ? `${context.formattedValue.value} ${unit}` : context.formattedValue.value;
+    // `text` is not a typed TextInput prop; it is the native prop ReText uses to update text without re-rendering children.
+    return { text, defaultValue: text } as unknown as Partial<TextInputProps>;
+  }, [unit, context.formattedValue]);
+
+  if (children) {
+    return <>{children(context)}</>;
+  }
+
+  return (
+    <AnimatedTextInput
+      editable={false}
+      pointerEvents="none"
+      underlineColorAndroid="transparent"
+      animatedProps={animatedProps}
+      style={[styles.value, { minWidth: valueWidth }, valueStyle, unitStyle]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  value: {
+    fontSize: VALUE_FONT_SIZE,
+    fontWeight: '600',
+    flexShrink: 0,
+    textAlign: 'center',
+    fontVariant: ['tabular-nums'],
+    color: '#111827',
+    padding: 0,
+  },
+});

package/platforms/react-native/solutions/components/Ruler/files/index.ts

@@ -0,0 +1,23 @@
+import Container from './Common';
+import { useRuler } from './Context';
+import Track from './Track';
+import Value from './Value';
+
+type TContainer = typeof Container;
+type TValue = typeof Value;
+type TTrack = typeof Track;
+type TUseRuler = typeof useRuler;
+
+interface IRuler extends TContainer {
+  Value: TValue;
+  Track: TTrack;
+  useRuler: TUseRuler;
+}
+
+const Ruler = Container as IRuler;
+Ruler.Value = Value;
+Ruler.Track = Track;
+Ruler.useRuler = useRuler;
+
+export default Ruler;
+export { useRuler };

package/platforms/react-native/solutions/components/Ruler/files/ruler.constants.ts

@@ -0,0 +1,70 @@
+import type {
+  IRulerTrackVisualConfig,
+  TRulerCaptionAlign,
+  TRulerDecelerationRate,
+  TRulerTrackAlign,
+} from './ruler.types';
+
+export const DEFAULT_RULER_STEP = 1;
+export const DEFAULT_FRACTION_DIGITS = 0;
+
+export const DEFAULT_GAP_BETWEEN_STEPS = 10;
+export const DEFAULT_STEP_WIDTH = 2;
+export const DEFAULT_SHORT_STEP_HEIGHT = 20;
+export const DEFAULT_LONG_STEP_HEIGHT = 40;
+export const DEFAULT_MINOR_STEP_HEIGHT = 12;
+export const DEFAULT_LONG_STEP_INTERVAL = 10;
+export const DEFAULT_INDICATOR_SIZE = 80;
+
+export const DEFAULT_INDICATOR_COLOR = '#6366F1';
+export const DEFAULT_SHORT_STEP_COLOR = '#E5E7EB';
+export const DEFAULT_LONG_STEP_COLOR = '#9CA3AF';
+export const DEFAULT_MINOR_STEP_COLOR = '#F3F4F6';
+
+export const DEFAULT_DECELERATION_RATE: TRulerDecelerationRate = 'normal';
+
+export const RULER_SNAP_TIMING_CONFIG = {
+  duration: 120,
+};
+
+export const RULER_MIN_FLING_VELOCITY = 80;
+
+export const RULER_OFFSET_ALIGN_EPSILON = 0.5;
+
+export const RULER_CONTROLLED_TIMING_CONFIG = {
+  duration: 100,
+};
+
+export const DEFAULT_SHOW_CAPTIONS = true;
+export const DEFAULT_CAPTION_INTERVALS = [1, 5, 10];
+export const DEFAULT_CAPTION_COLOR = '#6B7280';
+export const DEFAULT_CAPTION_FONT_SIZE = 12;
+export const DEFAULT_CAPTION_PADDING = 6;
+
+export const CAPTION_TIER_MID = 5;
+export const CAPTION_TIER_HIGH = 10;
+
+export const DEFAULT_TRACK_ALIGN: TRulerTrackAlign = 'center';
+export const DEFAULT_CAPTION_ALIGN: TRulerCaptionAlign = 'end';
+
+export const DEFAULT_TRACK_VISUAL: IRulerTrackVisualConfig = {
+  orientation: 'horizontal',
+  indicatorColor: DEFAULT_INDICATOR_COLOR,
+  shortStepColor: DEFAULT_SHORT_STEP_COLOR,
+  longStepColor: DEFAULT_LONG_STEP_COLOR,
+  gapBetweenSteps: DEFAULT_GAP_BETWEEN_STEPS,
+  shortStepHeight: DEFAULT_SHORT_STEP_HEIGHT,
+  longStepHeight: DEFAULT_LONG_STEP_HEIGHT,
+  stepWidth: DEFAULT_STEP_WIDTH,
+  longStepInterval: DEFAULT_LONG_STEP_INTERVAL,
+  indicatorSize: DEFAULT_INDICATOR_SIZE,
+  decelerationRate: DEFAULT_DECELERATION_RATE,
+};
+
+export function resolveDeceleration(rate: TRulerDecelerationRate): number {
+  if (typeof rate === 'number') {
+    return rate;
+  }
+
+  return rate === 'fast' ? 0.99 : 0.998;
+}

package/platforms/react-native/solutions/components/Ruler/files/ruler.types.ts

@@ -0,0 +1,98 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, TextStyle, ViewStyle } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+
+export type TRulerOrientation = 'horizontal' | 'vertical';
+
+export type TRulerDecelerationRate = 'normal' | 'fast' | number;
+
+export type TRulerTrackAlign = 'start' | 'center' | 'end';
+
+export type TRulerCaptionAlign = 'start' | 'end';
+
+export type TRulerTickTier = 'long' | 'medium' | 'minor';
+
+export interface IRulerMathConfig {
+  min: number;
+  max: number;
+  step: number;
+  stepSize: number;
+  stepCount: number;
+}
+
+export interface IRulerTrackVisualConfig {
+  orientation: TRulerOrientation;
+  indicatorColor: string;
+  shortStepColor: string;
+  longStepColor: string;
+  gapBetweenSteps: number;
+  shortStepHeight: number;
+  longStepHeight: number;
+  stepWidth: number;
+  longStepInterval: number;
+  indicatorSize: number;
+  decelerationRate: TRulerDecelerationRate;
+}
+
+export interface IRulerProps {
+  min: number;
+  max: number;
+  step?: number;
+  fractionDigits?: number;
+  value?: number;
+  defaultValue?: number;
+  onChange?: (value: number) => void;
+  onChangeEnd?: (value: number) => void;
+  children?: ReactNode;
+}
+
+export interface IRulerTrackProps {
+  orientation?: TRulerOrientation;
+  indicatorColor?: string;
+  shortStepColor?: string;
+  longStepColor?: string;
+  gapBetweenSteps?: number;
+  shortStepHeight?: number;
+  longStepHeight?: number;
+  stepWidth?: number;
+  /** Value interval between long ticks (e.g. `1` places long ticks at 1, 2, 3…). Defaults to the sole `captionIntervals` entry, otherwise `10`. */
+  longStepInterval?: number;
+  indicatorSize?: number;
+  decelerationRate?: TRulerDecelerationRate;
+  showCaptions?: boolean;
+  captionIntervals?: number[];
+  captionColor?: string;
+  captionFontSize?: number;
+  trackAlign?: TRulerTrackAlign;
+  captionAlign?: TRulerCaptionAlign;
+  /** Visual-only finer tick interval between selectable `step` positions. */
+  subStep?: number;
+  minorStepHeight?: number;
+  minorStepColor?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+export interface IRulerValueProps {
+  unit?: string;
+  unitStyle?: StyleProp<TextStyle>;
+  valueStyle?: StyleProp<TextStyle>;
+  children?: (ctx: IRulerContextValue) => ReactNode;
+}
+
+export interface IRulerContextValue {
+  value: SharedValue<number>;
+  formattedValue: SharedValue<string>;
+  offset: SharedValue<number>;
+  isDragging: SharedValue<boolean>;
+  min: number;
+  max: number;
+  step: number;
+  fractionDigits: number;
+  stepCount: number;
+  stepSize: SharedValue<number>;
+  maxOffset: SharedValue<number>;
+  trackVisual: IRulerTrackVisualConfig;
+  viewportWidth: SharedValue<number>;
+  viewportHeight: SharedValue<number>;
+  updateTrackVisual: (config: Partial<IRulerTrackVisualConfig>) => void;
+}

package/platforms/react-native/solutions/components/Ruler/files/ruler.utils.ts

@@ -0,0 +1,332 @@
+import {
+  DEFAULT_CAPTION_INTERVALS,
+  DEFAULT_LONG_STEP_INTERVAL,
+  RULER_OFFSET_ALIGN_EPSILON,
+} from './ruler.constants';
+import type { IRulerMathConfig, TRulerCaptionAlign, TRulerTickTier, TRulerTrackAlign } from './ruler.types';
+
+export function clamp(value: number, min: number, max: number): number {
+  'worklet';
+
+  return Math.min(max, Math.max(min, value));
+}
+
+export function getStepCount(min: number, max: number, step: number): number {
+  return Math.round((max - min) / step);
+}
+
+export function getStepSize(stepWidth: number, gapBetweenSteps: number): number {
+  return stepWidth + gapBetweenSteps;
+}
+
+export function getMaxOffset(stepCount: number, stepSize: number): number {
+  return stepCount * stepSize;
+}
+
+export function valueToIndex(value: number, min: number, step: number): number {
+  'worklet';
+
+  return Math.round((value - min) / step);
+}
+
+export function indexToValue(index: number, min: number, step: number, max: number): number {
+  'worklet';
+
+  return clamp(min + index * step, min, max);
+}
+
+export function valueToOffset(value: number, config: IRulerMathConfig): number {
+  'worklet';
+
+  const index = valueToIndex(value, config.min, config.step);
+  const clampedIndex = clamp(index, 0, config.stepCount);
+  return clampedIndex * config.stepSize;
+}
+
+export function offsetToIndex(offset: number, stepSize: number): number {
+  'worklet';
+
+  return Math.round(offset / stepSize);
+}
+
+export function offsetToValue(offset: number, config: IRulerMathConfig): number {
+  'worklet';
+
+  const index = offsetToIndex(offset, config.stepSize);
+  const clampedIndex = clamp(index, 0, config.stepCount);
+  return indexToValue(clampedIndex, config.min, config.step, config.max);
+}
+
+export function snapOffset(offset: number, config: IRulerMathConfig): number {
+  'worklet';
+
+  const index = offsetToIndex(offset, config.stepSize);
+  const clampedIndex = clamp(index, 0, config.stepCount);
+  return clampedIndex * config.stepSize;
+}
+
+export function rescaleOffsetToStepSize(
+  offset: number,
+  fromStepSize: number,
+  toStepSize: number,
+  stepCount: number,
+): number {
+  'worklet';
+
+  const index = clamp(offsetToIndex(offset, fromStepSize), 0, stepCount);
+  return index * toStepSize;
+}
+
+export function isOffsetAligned(offset: number, stepSize: number, epsilon?: number): boolean {
+  'worklet';
+
+  if (stepSize <= 0) {
+    return true;
+  }
+
+  const _epsilon = epsilon || RULER_OFFSET_ALIGN_EPSILON;
+  const nearestIndex = Math.round(offset / stepSize);
+  return Math.abs(offset - nearestIndex * stepSize) < _epsilon;
+}
+
+/**
+ * Returns the largest interval (e.g. 10 > 5 > 1) that `delta` is a multiple of,
+ * or `null` when `delta` does not align with any of the provided intervals.
+ */
+export function isValueOnInterval(delta: number, interval: number, epsilon = 1e-6): boolean {
+  'worklet';
+
+  if (interval <= 0) {
+    return false;
+  }
+
+  const absDelta = Math.abs(delta);
+  const remainder = absDelta % interval;
+  const distanceToMultiple = Math.min(remainder, interval - remainder);
+
+  return distanceToMultiple < epsilon;
+}
+
+export function isLongStep(index: number, min: number, step: number, max: number, longStepInterval: number): boolean {
+  'worklet';
+
+  const value = indexToValue(index, min, step, max);
+  return isValueOnInterval(value - min, longStepInterval);
+}
+
+export function getTickTier(
+  value: number,
+  min: number,
+  step: number,
+  longStepInterval: number,
+  subStep?: number,
+): TRulerTickTier | null {
+  'worklet';
+
+  const delta = value - min;
+
+  if (isValueOnInterval(delta, longStepInterval)) {
+    return 'long';
+  }
+
+  if (isValueOnInterval(delta, step)) {
+    return 'medium';
+  }
+
+  if (subStep !== undefined && subStep > 0 && isValueOnInterval(delta, subStep)) {
+    return 'minor';
+  }
+
+  return null;
+}
+
+export function getSubStepsPerMainStep(step: number, subStep: number): number {
+  return Math.round(step / subStep);
+}
+
+export function validateSubStep(step: number, subStep: number): void {
+  if (subStep <= 0) {
+    throw new Error('Ruler: `subStep` must be greater than 0.');
+  }
+
+  if (subStep >= step) {
+    throw new Error('Ruler: `subStep` must be less than `step`.');
+  }
+
+  if (!isValueOnInterval(step, subStep)) {
+    throw new Error('Ruler: `step` must be an even multiple of `subStep`.');
+  }
+}
+
+export function deriveLongStepIntervalFromStep(step: number): number {
+  return step * 2;
+}
+
+export function resolveLongStepInterval(
+  longStepInterval: number | undefined,
+  captionIntervals: number[],
+  step?: number,
+  fallback = DEFAULT_LONG_STEP_INTERVAL,
+): number {
+  if (longStepInterval !== undefined) {
+    return longStepInterval;
+  }
+
+  if (captionIntervals.length === 1) {
+    const interval = captionIntervals[0];
+
+    if (step === undefined || interval >= step) {
+      return interval;
+    }
+
+    return deriveLongStepIntervalFromStep(step);
+  }
+
+  if (step !== undefined && step > Math.max(...captionIntervals)) {
+    return deriveLongStepIntervalFromStep(step);
+  }
+
+  return fallback;
+}
+
+export function getCaptionTier(delta: number, intervals: number[] = DEFAULT_CAPTION_INTERVALS): number | null {
+  'worklet';
+
+  const epsilon = 1e-6;
+  const absDelta = Math.abs(delta);
+  const sortedDescending = [...intervals].filter(interval => interval > 0).sort((a, b) => b - a);
+
+  for (const interval of sortedDescending) {
+    if (isValueOnInterval(absDelta, interval, epsilon)) {
+      return interval;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Computes the static list of step indices (from `min`) that should render a caption,
+ * based on which value deltas align with one of `intervals`.
+ */
+export function getCaptionIndices(
+  min: number,
+  max: number,
+  step: number,
+  intervals: number[] = DEFAULT_CAPTION_INTERVALS,
+): number[] {
+  const stepCount = getStepCount(min, max, step);
+  const indices: number[] = [];
+
+  for (let index = 0; index <= stepCount; index += 1) {
+    const value = indexToValue(index, min, step, max);
+    const delta = value - min;
+
+    if (getCaptionTier(delta, intervals) !== null) {
+      indices.push(index);
+    }
+  }
+
+  return indices;
+}
+
+export function formatRulerValue(value: number, fractionDigits: number): string {
+  'worklet';
+
+  return value.toFixed(fractionDigits);
+}
+
+/**
+ * Ticks are positioned at `viewport / 2 + index * stepSize - offset`; this
+ * returns the index range whose positions fall inside the viewport (with one
+ * step of slack on both sides).
+ */
+export function getVisibleTickRange(
+  offset: number,
+  viewport: number,
+  stepSize: number,
+  stepCount: number,
+): { start: number; end: number } {
+  'worklet';
+
+  const halfViewport = viewport / 2;
+  const start = Math.floor((offset - halfViewport - stepSize) / stepSize);
+  const end = Math.ceil((offset + halfViewport + stepSize) / stepSize);
+  return {
+    start: clamp(start, 0, stepCount),
+    end: clamp(end, 0, stepCount),
+  };
+}
+
+/**
+ * Resolves the cross-axis origin (top for horizontal, left for vertical) of
+ * a piece of content (a tick, the indicator, ...) within the available
+ * cross-axis space, based on the requested alignment.
+ */
+export function resolveCrossAxisOrigin(crossAxisSize: number, contentSize: number, align: TRulerTrackAlign): number {
+  'worklet';
+
+  if (crossAxisSize <= 0 || contentSize <= 0) {
+    return 0;
+  }
+
+  if (align === 'start') {
+    return 0;
+  }
+
+  if (align === 'end') {
+    return Math.max(0, crossAxisSize - contentSize);
+  }
+
+  return Math.max(0, (crossAxisSize - contentSize) / 2);
+}
+
+export interface ITrackBandLayout {
+  tickBandOrigin: number;
+  captionBandOrigin: number;
+}
+
+/**
+ * Reserves non-overlapping cross-axis bands for the tick and caption groups.
+ *
+ * The ticks and captions are treated as a single block: `trackAlign` places
+ * that block within the cross-axis space, `captionAlign` decides on which
+ * side of the ticks the captions are rendered.
+ */
+export function resolveTrackBandLayout(
+  crossAxisSize: number,
+  tickBandSize: number,
+  captionBandSize: number,
+  padding: number,
+  trackAlign: TRulerTrackAlign,
+  captionAlign: TRulerCaptionAlign,
+  showCaptions: boolean,
+): ITrackBandLayout {
+  'worklet';
+
+  const hasCaptions = showCaptions && captionBandSize > 0;
+  const captionSpace = hasCaptions ? captionBandSize + padding : 0;
+  const blockOrigin = resolveCrossAxisOrigin(crossAxisSize, tickBandSize + captionSpace, trackAlign);
+
+  if (hasCaptions && captionAlign === 'start') {
+    return {
+      captionBandOrigin: blockOrigin,
+      tickBandOrigin: blockOrigin + captionSpace,
+    };
+  }
+
+  return {
+    tickBandOrigin: blockOrigin,
+    captionBandOrigin: blockOrigin + tickBandSize + padding,
+  };
+}
+
+export function validateRulerProps(min: number, max: number, step: number): void {
+  if (min >= max) {
+    throw new Error('Ruler: `min` must be less than `max`.');
+  }
+
+  if (step <= 0) {
+    throw new Error('Ruler: `step` must be greater than 0.');
+  }
+}

package/platforms/react-native/solutions/components/Ruler/solution.js

@@ -0,0 +1,38 @@
+export default {
+  "id": "component:Ruler",
+  "type": "component",
+  "platforms": [
+    "react-native"
+  ],
+  "title": "Ruler",
+  "description": "Ruler from the previous template kit. Treat the API as experimental until it is wired into a screen.",
+  "status": "experimental",
+  "since": "1.0.0",
+  "tags": [
+    "ui",
+    "kit"
+  ],
+  "requires": [],
+  "dependencies": [],
+  "files": [
+    {
+      "from": "files",
+      "to": "ui/components/Ruler"
+    }
+  ],
+  "register": [
+    {
+      "file": "ui/components/index.ts",
+      "marker": "components-import",
+      "code": "import Ruler from './Ruler';\n"
+    },
+    {
+      "file": "ui/components/index.ts",
+      "marker": "components-export",
+      "code": "  Ruler,\n"
+    }
+  ],
+  "manual": [],
+  "api": "Default export from ui/components/Ruler.",
+  "example": "import Ruler from '@components/Ruler';"
+};

package/platforms/react-native/solutions/components/Section/README.md

@@ -0,0 +1,29 @@
+# Section
+
+Segmented section control.
+
+## API
+
+Section with data, onChange, and variant.
+
+## Example
+
+```tsx
+<Section data={tabs} onChange={setTab} />
+```
+
+## Dependencies
+
+None beyond the setup baseline.
+
+No other solutions are required.
+
+## Manual steps
+
+None.
+
+## Added in
+
+1.0.0 (`stable`).
+
+Install with `forge g add --id component:Section`.