chemical_docs/pages/api/TablePage.tsx

import React from 'react';
import { ContentPage } from '../../components/ContentPage';
import { ApiSection } from '../../types';

const tableApi: ApiSection[] = [
  {
    title: 'Chemical.Table',
    description: 'Creates a reactive array (table with numerical indices). Changes to the array structure can trigger updates in dependent Computeds and Effects. For reactivity of individual elements, those elements would typically be Chemical.Value objects if fine-grained updates on element changes are needed, though this pattern is more common within Reactions.',
    entries: [
      {
        signature: 'Chemical.Table<T[]>(initialArray: T[]): Table<T[]>',
        description: 'Constructs a new reactive Table object.',
        parameters: [
          { name: 'initialArray', type: 'T[]', description: 'The initial array (plain Lua table) to store.' },
        ],
        returns: { type: 'Table<T[]>', description: 'A new Table object.' },
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local userScores = Table({100, 150, 90})
local userNames = Table({"Alice", "Bob"})
        `,
        notes: "Chemical.Table is best used with arrays of primitive values or plain tables. If you need an array of reactive objects, consider if a Reaction is more appropriate for managing that collection, especially for networked state."
      },
    ],
  },
  {
    title: 'Table Methods',
    entries: [
      {
        signature: 'table:get(): T[]',
        description: 'Retrieves the current array. If called within a Computed or Effect, it establishes a dependency on this Table.',
        returns: { type: 'T[]', description: 'The current array.' },
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local colors = Table({"red", "green"})
local currentColors = colors:get() -- currentColors is {"red", "green"}
        `,
      },
      {
        signature: 'table:set(newArray: T[])',
        description: 'Replaces the entire array with a new one. This is a significant change and will notify all dependents.',
        parameters: [
          { name: 'newArray', type: 'T[]', description: 'The new array (plain Lua table) to set.' },
        ],
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local items = Table({1, 2})
items:set({3, 4, 5}) -- items:get() is now {3, 4, 5}
        `,
      },
      {
        signature: 'table:insert(value: V)',
        description: 'Inserts a value at the end of the array.',
        parameters: [
          { name: 'value', type: 'V', description: 'The value to insert.' },
        ],
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local fruits = Table({"apple"})
fruits:insert("banana") -- fruits:get() is now {"apple", "banana"}
        `,
      },
      {
        signature: 'table:remove(value: V): V?',
        description: 'Removes the first occurrence of the specified value from the array. Returns the removed value, or nil if not found.',
        parameters: [
          { name: 'value', type: 'V', description: 'The value to remove.' },
        ],
        returns: { type: 'V?', description: 'The removed value or nil.' },
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local numbers = Table({10, 20, 30, 20})
numbers:remove(20) -- numbers:get() is now {10, 30, 20}
        `,
      },
      {
        signature: 'table:find(value: V): number?',
        description: 'Finds the index of the first occurrence of a value in the array.',
        parameters: [
          { name: 'value', type: 'V', description: 'The value to find.' },
        ],
        returns: { type: 'number?', description: 'The index of the value, or nil if not found.' },
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local letters = Table({'a', 'b', 'c'})
local indexB = letters:find('b') -- indexB is 2
local indexD = letters:find('d') -- indexD is nil
        `,
      },
      {
        signature: 'table:setAt(index: number, value: V)',
        description: 'Sets the value at a specific index in the array.',
        parameters: [
          { name: 'index', type: 'number', description: 'The 1-based index to set.' },
          { name: 'value', type: 'V', description: 'The value to set at the index.' },
        ],
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local data = Table({1, 2, 3})
data:setAt(2, 99) -- data:get() is now {1, 99, 3}
        `,
      },
      {
        signature: 'table:getAt(index: number): V?',
        description: 'Retrieves the value at a specific index in the array.',
        parameters: [
          { name: 'index', type: 'number', description: 'The 1-based index to get.' },
        ],
        returns: { type: 'V?', description: 'The value at the index, or nil if out of bounds.' },
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local names = Table({"Eve", "Adam"})
local firstName = names:getAt(1) -- firstName is "Eve"
        `,
      },
      {
        signature: 'table:clear()',
        description: 'Removes all elements from the array.',
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local tasks = Table({"task1", "task2"})
tasks:clear() -- tasks:get() is now {}
        `,
      },
      {
        signature: 'table:destroy()',
        description: 'Destroys the Table object and its resources.',
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local activeUsers = Table({"userA"})
-- ...
activeUsers:destroy()
        `,
      },
      {
        signature: '#table: number (via __len metamethod)',
        description: 'Returns the number of elements in the array. Can be accessed using the `#` operator.',
        returns: { type: 'number', description: 'The length of the array.'},
        example: `
local Chemical = require(game.ReplicatedStorage.Chemical)
local Table = Chemical.Table

local list = Table({10, 20, 30})
print(#list) -- Output: 3
        `
      }
    ],
  },
];

export const TablePage: React.FC = () => {
  return <ContentPage title="Chemical.Table" sections={tableApi} />;
};