Initial commit

docs/api/creation.md

@@ -0,0 +1,325 @@
+# Element Creation API
+
+<br/>
+
+## create()
+
+Creates a new UI element, applying any given properties.
+
+### Type
+
+```lua
+function create(classNameOrInstance: string | Instance): (properties: Map<string, any>) -> Instance
+```
+
+### Details
+
+The function can take either a `string` or an `Instance` as its first argument.
+
+- If given a `string`, a new instance with the string class name will be created with default properties already applied.
+- If given an `Instance`, a new instance that is a clone of the given instance will be created.
+
+This returns another function that is used to apply any properties to the new instance.
+
+### Example
+
+```lua
+local frame = create("Frame") {
+    Name = "NewFrame",
+    Position = UDim2.fromScale(1, 0)
+}
+
+-- creates a clone of `frame` with new properties applied.
+local frame2 = create(frame) {
+    Size = UDim2.fromOffset(50, 100)
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## apply()
+
+Applies any given properties to a given instance.
+
+### Type
+
+```lua
+function apply(instance: Instance): (properties: Map<string, any>) -> Instance
+```
+
+### Details
+
+Applies properties in the same manner as `create` for already existing existances.
+
+Can use symbols and bind state just like `create`.
+
+### Example
+
+```lua
+local frame = Instance.new("Frame")
+
+apply(frame) {
+    Position = UDim2.fromScale(1, 0)
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Layout
+
+Symbol used to pass layout properties to elements.
+
+### Type
+
+```lua
+type Layout = Symbol
+
+type LayoutProps = {
+    [Symbol] = {
+        -- These are all properties considered to be "layout properties"
+        AnchorPoint: Prop<Vector2>?;
+        LayoutOrder: Prop<number>?;
+        Position: Prop<UDim2>?;
+        Rotation: Prop<number>?;
+        Size: Prop<UDim2>?;
+        SizeConstraint: Prop<Enum.SizeConstraint>?;
+        Visible: Prop<boolean>?;
+        ZIndex: Prop<number>?; 
+    }
+}
+
+type Prop<T> = T | State<T>
+```
+
+### Details
+
+The primary purpose of this symbol is to enable easy passthrough of layout properties
+through user-defined component hierarchies.
+
+It is recommended to only set layout properties using the `Layout` symbol when using
+your own components.
+
+### Example
+
+```lua
+local function BlackFrame(props)
+    return create("Frame") {
+        BackgroundColor3 = Color3.new(0, 0, 0),
+        [Layout] = props[Layout]
+    }
+end
+
+BlackFrame {
+    [Layout] = {
+        AnchorPoint = Vector2.new(0.5, 0.5),
+        Position = UDim2.fromScale(0.5, 0.5),
+        Size = UDim2.fromOffset(100, 50)
+    }
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Children
+
+Symbol used to pass child instances to elements.
+
+### Type
+
+```lua
+type Children = Symbol
+
+type ChildrenProps = {
+    [Symbol] = ChildrenProp
+}
+
+type ChildrenProp = Prop<Instance> | Array<ChildrenProp>
+```
+
+### Details
+
+This symbol is flexible in the way that children can be passed in the form of nested arrays.
+
+Children can also be assigned using a state binding.
+
+### Example
+
+```lua
+create("Frame") {
+    -- all of the below are valid methods of assigning children
+    [Children] = create("TextLabel") {},
+
+    [Children] = {
+        create("TextLabel") {},
+        create("TextLabel") {},
+    },
+
+    [Children] = {
+        create("TextLabel") {},
+        {
+            create("TextLabel") {},
+        }
+    }
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Event
+
+Symbol used to connect callbacks to instance events.
+
+### Type
+
+```lua
+type Event = Map<string, Symbol>
+
+type EventProps = {
+    [Symbol] = Prop<(...unknown) -> ()>
+}
+```
+
+### Details
+
+The `Event` symbol can be indexed to get symbols to connect to specific events.
+
+Event parameters are passed into the callback.
+
+When callbacks are connected by binding to a state,
+connections are automatically disconnected when the state changes.
+
+### Example
+
+```lua
+create("TextButton") {
+    [Event.Activated] = function()
+        print("Clicked")
+    end
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Changed
+
+Symbol used to connect callbacks to instance property changed events.
+
+### Type
+
+```lua
+type Changed = Map<string, Symbol>
+
+type ChangedProps = {
+    [Symbol] = Prop<(...unknown) -> ()>
+}
+```
+
+### Details
+
+The `Changed` symbol can be indexed to get symbols to connect to specific events just like `Event`.
+
+Event parameters are passed into the callback.
+
+When callbacks are connected by binding to a state,
+connections are automatically disconnected when the state changes.
+
+### Example
+
+```lua
+create("TextBox") {
+    [Changed.Text] = function()
+        print("New text entered")
+    end
+}
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Bind
+
+Symbol used to bind states to instance properties.
+
+### Type
+
+```lua
+type Bind = Map<string, Symbol>
+
+type BindProps = {
+    [Symbol] = State<any>
+}
+```
+
+### Details
+
+The `Bind` symbol can be indexed to bind specific properties just like `Event`.
+
+Sets the given state value to the instance property value immediately after instance creation.
+
+When an instance property is changed, the value of the given state will automatically
+be set to the new property. Effectively a shorthand for connecting a property changed event
+to set state values.
+
+### Example
+
+```lua
+local text = wrap()
+
+local box = create("TextBox") {
+    [Bind.Text] = text
+}
+
+box.Text = "New text"
+print(text.Value) -- "New text"
+```
+
+-------------------------------------------------------------------
+
+<br/>
+
+## Created
+
+Symbol used to run a callback once immediately after instance creation.
+
+### Type
+
+```lua
+type Created = Symbol
+
+type CreatedProps = {
+    [Symbol] = (Instance) -> ()
+}
+```
+
+### Details
+
+The instance being defined with the `Created` symbol is passed as the first
+argument to the callback.
+
+### Example
+
+```lua
+local frame
+
+create("Frame") {
+    Name = "Background",
+    [Created] = function(instance)
+        frame = instance
+    end
+}
+
+print(frame.Name) -- "Background"
+```
+
+-------------------------------------------------------------------